Tool Output Parsing Failure Root-Cause Prompt

This prompt is designed for platform engineers and AI SREs who need to diagnose why an agent failed to parse a tool's response during a production run. The job-to-be-done is root-cause classification: given the raw tool output, the expected schema, and the parsing error, the prompt must determine whether the failure was caused by schema drift, an unexpected output format, truncation, or an encoding issue. The reader is expected to have access to production trace data, the agent's tool manifest, and the specific error log from the parsing layer. This is not a prompt for designing schemas or writing parsers; it is a diagnostic tool for incidents where a previously working integration suddenly breaks.

Use this prompt when you have a concrete parsing failure captured in your observability platform and you need a structured, evidence-backed classification before deciding on a fix. The prompt requires three critical inputs: the exact tool output that failed to parse, the expected schema or data contract, and the error message or exception from the parser. Without all three, the classification will be speculative. Do not use this prompt for general tool-call audits, argument validation, or workflow completeness checks—those are separate diagnostic workflows covered by sibling prompts in the Tool-Call and Function Sequence Audit group. This prompt is also unsuitable for real-time agent self-correction; it is a post-hoc trace review tool for engineering teams.

Before running this prompt, ensure you have isolated the specific tool call and its response from the trace. Strip any sensitive data from the tool output if it will leave your observability boundary. The prompt's output is a root-cause classification and a fix recommendation, but the recommendation should be treated as engineering guidance, not an automated repair. For high-severity incidents where the parsing failure caused data loss, incorrect state mutations, or user-facing errors, always pair the prompt's output with a manual review of the affected sessions and a rollback plan. After classification, feed the finding into your prompt versioning and change management process to prevent recurrence.

This prompt template is designed for platform engineers who need to diagnose why an agent failed to parse a tool's response. It takes a raw tool output, an expected schema, and a parsing error message, then classifies the failure into one of several root-cause categories: schema drift, unexpected format, truncation, encoding issues, or an unknown anomaly. The output includes a structured classification, a confidence score, and a concrete fix recommendation that can be routed to the responsible team.

textCopy
You are a production diagnostics assistant for an AI agent platform. Your task is to analyze a tool output parsing failure and determine the root cause.

## INPUT
- Tool Output: [TOOL_OUTPUT]
- Expected Schema: [EXPECTED_SCHEMA]
- Parsing Error Message: [PARSING_ERROR]
- Tool Name: [TOOL_NAME]
- Trace ID: [TRACE_ID]

## TASK
Classify the parsing failure into exactly one of the following root-cause categories:

1. **SCHEMA_DRIFT**: The tool output structure does not match the expected schema. Fields are missing, renamed, or have changed types.
2. **UNEXPECTED_FORMAT**: The tool returned a valid but unexpected format (e.g., plain text instead of JSON, HTML instead of CSV, a wrapper object that was not documented).
3. **TRUNCATION**: The tool output was cut off mid-stream, resulting in incomplete or malformed syntax.
4. **ENCODING_ISSUE**: The output contains characters, byte sequences, or escape patterns that break the parser (e.g., unescaped quotes, invalid UTF-8, BOM characters).
5. **UNKNOWN**: The failure does not clearly match any of the above categories.

## OUTPUT SCHEMA
Return a JSON object with the following fields:
- `trace_id`: string (the provided trace ID)
- `tool_name`: string (the provided tool name)
- `root_cause`: string (one of SCHEMA_DRIFT, UNEXPECTED_FORMAT, TRUNCATION, ENCODING_ISSUE, UNKNOWN)
- `confidence`: number between 0.0 and 1.0
- `evidence`: string (a concise explanation quoting specific parts of the tool output, schema, or error message that support the classification)
- `fix_recommendation`: string (a concrete, actionable recommendation for the team that owns the tool or the parsing layer)
- `requires_human_review`: boolean (set to true if the confidence is below 0.7 or the root_cause is UNKNOWN)

## CONSTRAINTS
- Do not hallucinate evidence. Quote directly from the provided inputs.
- If the tool output is truncated, check whether the truncation point aligns with the parsing error location.
- If the tool output appears valid against the schema, re-examine the error message for encoding or wrapper clues.
- For SCHEMA_DRIFT, identify the specific field or structural mismatch.
- For UNKNOWN classifications, set confidence to 0.5 or lower and flag for human review.

Adaptation guidance: Replace the five root-cause categories with your own taxonomy if your platform distinguishes additional failure modes such as timeout-induced partial responses, authentication error pages masquerading as tool outputs, or rate-limit responses. The output schema can be extended with fields like affected_field, schema_version_expected, or schema_version_observed if your tools are versioned. For high-volume triage, consider adding a severity field (LOW, MEDIUM, HIGH, CRITICAL) based on whether the parsing failure blocked the agent's workflow or was handled by a fallback. Always validate the model's JSON output against the schema before routing the result to an incident queue or dashboard.

This prompt is designed to be called programmatically as part of an automated failure-recovery or alerting workflow, not as a one-off manual investigation. When an agent's tool-call step fails with a parsing error, the application should catch the exception, extract the raw tool output, the expected schema, and the error message, and then invoke this prompt. The model's structured output—a root-cause classification and a fix recommendation—should be logged alongside the trace for immediate diagnosis and, where safe, used to trigger an automated repair or a human review ticket.

To integrate this, build a lightweight service function that accepts a tool_output string, a schema object (JSON Schema or a Pydantic model definition), and a parsing_error string. The function should format these into the prompt's [TOOL_OUTPUT], [EXPECTED_SCHEMA], and [PARSING_ERROR] placeholders. Before sending the request, validate that the tool_output is not empty and that the parsing_error is a non-null string; if these preconditions fail, log an INVALID_DIAGNOSTIC_INPUT event and abort. Use a model with strong JSON mode support (e.g., GPT-4o, Claude 3.5 Sonnet) and set response_format to json_schema using the RootCauseOutput schema defined in the prompt. Implement a retry with exponential backoff (max 2 retries) only for transient API errors (5xx status codes), not for validation failures. After receiving the response, validate that the root_cause field matches one of the allowed enum values (SCHEMA_DRIFT, UNEXPECTED_FORMAT, TRUNCATION, ENCODING_ERROR, UNKNOWN). If validation fails, log the raw response and escalate to a human review queue with the original trace ID.

For high-risk domains where a misclassified root cause could lead to an incorrect automated fix (e.g., silently dropping a malformed financial transaction), do not automatically apply the fix_recommendation. Instead, route the validated diagnostic output to a human-in-the-loop review step. The reviewer can then approve the recommended fix, choose a different remediation, or mark the trace for further manual investigation. Always attach the full prompt input and model output to the trace for auditability. Avoid using this prompt on tool outputs that exceed the model's context window; if the raw output is larger than 100,000 characters, truncate it intelligently by keeping the first 50,000 and last 50,000 characters, and prepend a [TRUNCATED_FOR_DIAGNOSIS] marker to prevent a false TRUNCATION classification.