Agent Action Decision Log Prompt

This prompt is designed for AI operations engineers, SREs, and compliance officers who need to understand why an agent chose a specific tool at a specific moment. It transforms an opaque tool selection event into a structured, auditable decision record. The primary job-to-be-done is debugging multi-step agent failures and proving governance by capturing the agent's stated reasoning, alternatives considered, confidence level, and the policy constraints active during tool selection. This is not a prompt for generating tool calls; it is a post-hoc analysis prompt that takes an existing tool call event and its surrounding context to produce a human-readable and machine-parseable rationale.

Use this prompt when you have a log of a tool call but lack the 'why' behind it. The ideal user has access to the agent's full context window or a summary of its state immediately before the tool was invoked, including the system prompt, tool descriptions, and recent conversation history. You should not use this prompt for real-time tool selection enforcement—it is an observability tool, not a gating mechanism. It is also unsuitable for agents with extremely limited context where the reasoning is self-evident, or for simple, deterministic tool chains where the selection logic is hardcoded in application code rather than decided by the model.

The output is a structured JSON record containing fields like decision_rationale, alternatives_considered, confidence_score, and policy_constraints_checked. This record is designed to be ingested by log aggregation systems, audit databases, or debugging dashboards. Before shipping this prompt to production, you must define evaluation criteria that check for missing rationale fields, generic or circular reasoning (e.g., 'I chose it because it was the right tool'), and hallucinations where the agent references tools or policies not present in the provided context. A human review step is critical for high-risk domains like finance or healthcare, where an incorrect decision record could mask a serious compliance violation.

To get started, gather a sample of agent tool call events and their preceding context. Run the prompt template against these samples and manually inspect the output for faithfulness to the provided context. Pay close attention to the alternatives_considered field—a common failure mode is the agent listing tools that were not actually available or failing to mention a clearly superior alternative. Once you are confident in the output quality, integrate the prompt into your agent's post-tool-call logging pipeline, ensuring that every decision record is validated against your schema before being written to permanent storage.

This template is the core instruction set you will send to a model to produce an Agent Action Decision Log. It is designed to be invoked immediately after an agent selects a tool but before execution, or retrospectively from a trace. The prompt forces the model to articulate its reasoning, enumerate considered alternatives, state its confidence, and reference the specific policy constraints that shaped its decision. Use this template as a starting point: you will need to populate the placeholders with your specific tool catalog, session context, and organizational policies.

textCopy
You are an observability recorder for an AI agent. Your only job is to produce a structured decision log explaining why the agent chose a specific tool. Do not execute any tool. Do not continue the agent's task.

## Inputs
- [AGENT_ROLE_DESCRIPTION]
- [CURRENT_TASK_AND_GOAL]
- [AVAILABLE_TOOLS_WITH_SCHEMAS]
- [TOOL_SELECTED_BY_AGENT]
- [AGENT_PROPOSED_ARGUMENTS]
- [RECENT_AGENT_REASONING_TRACE]
- [APPLICABLE_POLICIES_AND_SCOPE]

## Output Schema
Produce a single JSON object conforming to this structure:
{
  "decision_log": {
    "timestamp": "ISO 8601",
    "session_id": "string",
    "agent_role": "string",
    "task_summary": "One-sentence summary of the agent's current goal.",
    "tool_selected": {
      "name": "string",
      "arguments": {},
      "rationale": "Explain why this tool was chosen over others."
    },
    "alternatives_considered": [
      {
        "tool_name": "string",
        "reason_rejected": "Specific reason, e.g., insufficient scope, higher latency, policy violation."
      }
    ],
    "confidence_assessment": {
      "score": "0.0 to 1.0",
      "factors": ["List of factors increasing or decreasing confidence."]
    },
    "policy_evaluation": {
      "policies_checked": ["Policy names and versions"],
      "constraint_violations": ["Any policy violations detected, or 'none'"],
      "requires_approval": true_or_false
    },
    "risk_notes": "Any noted risks, edge cases, or uncertainty about the tool's outcome."
  }
}

## Constraints
- If fewer than two alternatives were considered, explain why in the rationale.
- If confidence is below [CONFIDENCE_THRESHOLD], flag `requires_approval` as true.
- Reference specific policy names from [APPLICABLE_POLICIES_AND_SCOPE]. Do not invent policies.
- If the agent's reasoning trace is empty or truncated, set confidence to 0.0 and note the missing data.

To adapt this template, replace each square-bracket placeholder with data from your agent runtime. The [AVAILABLE_TOOLS_WITH_SCHEMAS] should be a complete dump of the tool definitions the agent saw at decision time, not a curated subset. The [RECENT_AGENT_REASONING_TRACE] is critical for fidelity; if your agent framework does not produce a reasoning trace, you must either add one or accept that the decision log will have low confidence and limited diagnostic value. For high-risk domains, wire the output of this prompt into a human review queue before the tool is executed, using the requires_approval boolean as a routing signal.

The Agent Action Decision Log prompt is not a standalone artifact—it is a synchronous interceptor that must execute inside the agent's tool-selection loop, after the model has chosen a tool but before the tool is invoked. The harness calls the LLM with this prompt, passing the agent's current state, the proposed tool call, and the list of alternative tools that were available. The output is a structured decision record that must be validated, persisted to the audit log, and optionally used to gate tool execution if the rationale is missing, incoherent, or violates a policy constraint. This prompt is high-stakes: a missing or malformed decision record can create a compliance gap, so the harness must treat a failure to produce a valid record as a blocking error, not a warning.

Integration point: Insert this prompt inside the agent's select_tool or pre_invoke hook. The harness must supply [AGENT_STATE] (current task, conversation history, memory), [PROPOSED_TOOL] (the tool name and arguments the model selected), [AVAILABLE_TOOLS] (the full tool registry with descriptions and capability metadata), [POLICY_CONSTRAINTS] (scope boundaries, rate limits, permission rules), and [CONFIDENCE_THRESHOLD] (the minimum self-reported confidence before escalation). Validation: After the LLM returns the decision record, validate that all required fields are present (rationale, alternatives_considered, confidence_score, policy_check_result, tool_selected, timestamp). If any field is missing or confidence_score is below [CONFIDENCE_THRESHOLD], route to a human approval queue or a fallback retry with a more explicit prompt variant. Retries: Use a single retry with an error message injected into [PREVIOUS_ERROR] if the first attempt fails validation. Do not retry more than once—escalate instead to avoid loop-based hallucinations.

Persistence and audit: Write every validated decision record to an append-only audit store with a unique decision_id, a hash of the agent state that produced it, and the model version used. This record becomes the primary evidence for compliance reviews and incident reconstruction. Model choice: Use a model with strong structured-output support (GPT-4o, Claude 3.5 Sonnet, or equivalent) and enforce JSON mode or structured outputs to prevent format drift. Observability: Emit a trace span for the decision-log generation step with the decision_id, latency, and validation status. If the decision record triggers an escalation, attach the record to the escalation ticket. What to avoid: Do not generate decision records asynchronously or in batch after the tool has already executed—the value is in the pre-execution rationale. Do not skip validation in production; a malformed decision record is worse than no record because it creates a false sense of audit readiness.