Agent Tool Observability Log Generation Prompt Template

Use this prompt when you need to convert raw, unstructured agent tool invocation data into a consistent, machine-readable observability log. The primary job-to-be-done is debugging multi-step agent failures and proving governance to auditors. The ideal user is an SRE, AI operations engineer, or platform developer who already captures raw tool call data—request payloads, responses, timestamps, and error codes—and needs to feed structured telemetry into an existing monitoring stack like Datadog, Grafana, or an OpenTelemetry collector. This prompt is a meta-prompt for your observability pipeline, not a prompt you give to the agent itself.

This prompt assumes you have a reliable feed of raw invocation data. It does not replace your agent's execution logic, nor does it instrument the agent to start capturing data. If you haven't solved raw data capture first, this prompt will produce incomplete or misleading logs. The prompt is designed for post-hoc log generation: you feed it a batch of raw invocations, and it outputs structured log entries with span correlation IDs, an error taxonomy (e.g., timeout, auth_failure, malformed_response), and a latency breakdown. It is particularly valuable when you have dozens of tool calls across multiple agents and need to trace a single failure back to its root cause without manually reconstructing the sequence.

Do not use this prompt for real-time agent decision-making or as a guardrail during tool execution. It is an offline observability tool. If you need to block a tool call based on its arguments, validate a response before it re-enters the agent's context, or enforce a circuit breaker, use the Tool Input Validation, Tool Output Sanitization, or Agent Tool Circuit Breaker Test prompts instead. For testing tool contracts before deployment, use the Tool Contract Validation Prompt. This prompt's value is in post-execution traceability, not in-line enforcement. After generating structured logs, the next step is typically to configure your monitoring platform to alert on error rate spikes, latency anomalies, or missing spans.

This prompt template is the core instruction set you send to a model to produce a structured observability log from a raw tool interaction. It is designed to be wired into an agent harness immediately after a tool call completes—before the agent acts on the result. The template forces the model to extract invocation details, response data, latency, and outcome classification into a consistent JSON schema, enabling correlation across spans and debugging of multi-step agent failures. Use it as a post-processing step in your agent loop, not as a conversational prompt.

textCopy
You are an observability logger for an AI agent system. Your only job is to convert a raw tool interaction into a structured, traceable log entry. Do not summarize, analyze, or act on the tool result. Output only the JSON log object.

## INPUT
- **Tool Name:** [TOOL_NAME]
- **Tool Call ID:** [CALL_ID]
- **Trace ID:** [TRACE_ID]
- **Span ID:** [SPAN_ID]
- **Parent Span ID:** [PARENT_SPAN_ID]
- **Invocation Timestamp (ISO 8601):** [INVOCATION_TIMESTAMP]
- **Arguments (escaped JSON):** [ARGUMENTS]
- **Raw Response (escaped JSON or string):** [RAW_RESPONSE]
- **Response Received Timestamp (ISO 8601):** [RESPONSE_TIMESTAMP]
- **HTTP Status Code (if applicable):** [HTTP_STATUS]
- **Retry Count:** [RETRY_COUNT]
- **Idempotency Key (if used):** [IDEMPOTENCY_KEY]

## OUTPUT SCHEMA
Produce a single JSON object with these exact fields:
{
  "log_version": "1.0",
  "trace_id": "string",
  "span_id": "string",
  "parent_span_id": "string | null",
  "tool_name": "string",
  "call_id": "string",
  "invocation_timestamp": "ISO 8601 string",
  "arguments": {},
  "response_payload": {},
  "response_timestamp": "ISO 8601 string",
  "latency_ms": "number",
  "http_status": "number | null",
  "retry_count": "number",
  "idempotency_key": "string | null",
  "outcome": "success | failure | timeout | rejected | unknown",
  "error": {
    "error_type": "string | null",
    "error_message": "string | null",
    "error_code": "string | null",
    "retryable": "boolean | null"
  },
  "response_size_bytes": "number | null",
  "tool_schema_version": "string | null"
}

## ERROR TAXONOMY
Classify errors into one of these types:
- `AUTHENTICATION_ERROR`: Invalid or expired credentials.
- `AUTHORIZATION_ERROR`: Insufficient permissions for the requested action.
- `INVALID_ARGUMENT`: The tool rejected one or more arguments as malformed or out of range.
- `RESOURCE_NOT_FOUND`: The target resource does not exist.
- `RATE_LIMITED`: The request was throttled.
- `TIMEOUT`: The tool did not respond within the expected window.
- `INTERNAL_ERROR`: The tool returned an unexpected 5xx or equivalent.
- `MALFORMED_RESPONSE`: The response did not match the declared output schema.
- `CONNECTION_ERROR`: Network-level failure before a response was received.
- `UNKNOWN`: The failure does not match any known category.

## CONSTRAINTS
1. Compute `latency_ms` as the difference between `response_timestamp` and `invocation_timestamp` in milliseconds.
2. If `http_status` is 2xx and the response is parseable, set `outcome` to `success` and `error` fields to `null`.
3. If `http_status` is 4xx or 5xx, set `outcome` to `failure` and populate the `error` object using the taxonomy above.
4. If no response was received and the call timed out, set `outcome` to `timeout`, `error_type` to `TIMEOUT`, and `response_payload` to `null`.
5. If the tool returned a 2xx but the response body does not match the expected schema, set `outcome` to `failure` and `error_type` to `MALFORMED_RESPONSE`.
6. Never fabricate fields. If a value is not provided in the input, use `null`.
7. Output only the JSON object. No markdown fences, no explanatory text.

To adapt this template, replace every square-bracket placeholder with actual values from your agent runtime before sending the prompt to the model. The [ARGUMENTS] and [RAW_RESPONSE] placeholders expect pre-serialized JSON strings—sanitize them first to avoid injection. If your observability backend requires additional fields (e.g., tenant_id, session_id), extend the output schema explicitly rather than relying on the model to infer them. For high-risk domains where log accuracy is critical, run the generated JSON through a schema validator and compare latency_ms against your own clock measurement before accepting the log entry.

This prompt is designed to be called as a post-hoc processing step immediately after a tool invocation completes, whether the call succeeded, failed, or timed out. The harness should intercept the raw tool request and response payloads, capture wall-clock timestamps, and inject them into the prompt's [TOOL_CALL_CONTEXT] placeholder. Do not rely on the agent's own summary of what happened—feed the actual wire-level data. The prompt's job is to normalize that raw data into a structured, queryable log entry, not to interpret or retry the call. For high-throughput systems, batch multiple tool calls into a single prompt invocation to amortize model latency, but ensure each log entry remains independently traceable via its span_id.

Implement a strict validation layer around the model's output before the log is written to your observability store. Parse the generated JSON and verify: (1) the span_id and trace_id match the input context exactly—reject any hallucinated identifiers; (2) the outcome field is one of the allowed enum values (success, error, timeout, denied); (3) the latency_ms field is a non-negative integer that falls within a reasonable bound of the measured latency (e.g., ±5% tolerance); and (4) the error_taxonomy field is populated if and only if outcome is not success. If validation fails, do not write the malformed log. Instead, retry the prompt once with the same input and an explicit [CONSTRAINTS] block that highlights the specific validation error. If the second attempt fails, write a minimal fallback log entry using the raw data you already have and flag it with log_quality: "fallback" for later inspection. This prevents a prompt failure from creating a gap in your audit trail.

For production deployment, route this prompt to a fast, cost-efficient model (such as Claude Haiku or GPT-4o-mini) because the task is extractive and structural, not generative. Reserve more capable models for the fallback path only. Wire the prompt's output into your existing tracing system (e.g., OpenTelemetry collectors, Datadog, or Honeycomb) by mapping the generated fields to span attributes. The error_taxonomy field should be indexed as a high-cardinality facet to enable SREs to query by failure category. Finally, set an alert on the ratio of log_quality: "fallback" entries to successful generations; if that ratio exceeds 1% over a rolling window, investigate the prompt's performance or the upstream tool's response shape for breaking changes.