Structured API Response Interpretation Prompt Template

This prompt is designed for full-stack AI engineers who need to translate raw, structured API responses (typically JSON) into coherent, user-facing natural language summaries. The core job-to-be-done is to extract only the fields relevant to the user's original request, suppress internal metadata (like HTTP headers, pagination tokens, or database row IDs), and present the information clearly without hallucinating unsupported details. The ideal user is building a tool-calling system—such as a copilot, support agent, or data-retrieval assistant—where the model must act as an intermediary between a backend API and a non-technical end user.

Use this prompt when the tool output is a single, complete, and well-formed JSON payload from a known API endpoint. It is specifically tuned for scenarios where the schema is predictable and the primary risk is the model inventing fields, misinterpreting null values, or exposing internal implementation details to the user. You should not use this prompt for multi-tool aggregation, error code interpretation, or empty-result handling; those scenarios require dedicated playbooks with different constraints. This prompt is also unsuitable for raw, unstructured text outputs or for cases where the API response is too large to fit in the context window without truncation.

Before implementing, ensure you have a clear mapping between the API response schema and the user-facing summary requirements. Define which fields are safe to expose, which must be suppressed, and how to handle null or missing values. The prompt includes placeholders for [INPUT] (the raw JSON), [CONTEXT] (the user's original question), and [OUTPUT_SCHEMA] (the expected structure of the summary). In high-stakes domains like finance or healthcare, always pair this prompt with a validation harness that checks for hallucinated fields and requires human review before the summary reaches the end user.

This template is the core instruction set for converting a structured tool or API response into a coherent, grounded summary. It is designed to be copied directly into your prompt management system, with placeholders that your application layer must resolve before inference. The template enforces strict grounding: every claim in the output must be traceable to a field in the input JSON. It also suppresses internal metadata (like HTTP headers, pagination tokens, or database row IDs) unless explicitly requested, preventing the model from leaking implementation details to the end user.

textCopy
You are an AI assistant that translates raw JSON API responses into clear, user-facing natural language summaries.

Your task is to process the JSON response provided in [API_RESPONSE] and produce a summary that answers the user's original request, which is provided in [USER_QUERY].

# Constraints
- [CONSTRAINTS]
- Every factual statement in your summary MUST be directly supported by a field or value present in [API_RESPONSE].
- If a requested piece of information is not present in [API_RESPONSE], explicitly state that it is unavailable instead of guessing or implying a value.
- Do not mention or describe raw JSON structure, field names, data types, or API mechanics unless the user explicitly asks about them.
- Suppress all internal metadata (e.g., "id", "created_at", "pagination", "_links") unless [INCLUDE_METADATA] is set to true.
- If [API_RESPONSE] contains an error object or a non-2xx status, follow the error handling instructions in [ERROR_HANDLING_RULES].

# Output Format
Your response must conform to the following schema:
[OUTPUT_SCHEMA]

# Examples of Good Summaries
[EXAMPLES]

# Risk Level and Escalation
[RISK_LEVEL]

# Available Tools for Follow-up
[TOOLS]

Now, process the following:

User Query: [USER_QUERY]
API Response: [API_RESPONSE]

To adapt this template, replace each square-bracket placeholder with concrete values at runtime. [CONSTRAINTS] should include domain-specific rules like 'Never disclose pricing to unauthenticated users' or 'Round all currency values to two decimal places.' [OUTPUT_SCHEMA] should be a strict JSON Schema or a descriptive text block defining the expected keys and types. [EXAMPLES] must contain at least one few-shot demonstration showing a raw JSON input and the ideal summary output; include a negative example where the model correctly abstains from answering due to missing data. [ERROR_HANDLING_RULES] should define the exact user-facing message for timeouts, 4xx, and 5xx errors. Before deploying, run this prompt through your evaluation harness using the test cases from the 'How to Test This Prompt' section of this playbook, paying special attention to hallucinated fields and schema conformance.

This prompt sits between a raw tool call result and the user-facing response. In a typical implementation, the application layer first executes the tool call (e.g., a REST API request, a database query, or an SDK method), captures the raw JSON response, and then passes that response into this prompt alongside the original user query and any relevant session context. The model's output is a structured natural language summary that must be validated before it reaches the user. Do not pass raw tool outputs directly to the user; always route them through an interpretation layer that can suppress internal metadata, error codes, and sensitive fields.

The implementation harness should enforce a strict contract. Before calling the model, validate that the tool output is parseable JSON and that required fields exist. After receiving the model's summary, run a schema validator to confirm the output matches the expected structure (e.g., a JSON object with summary, extracted_fields, and confidence_flags). Implement a hallucination check that compares every factual claim in the summary against the original tool output using string matching or embedding similarity. If the model references a field not present in the source JSON, flag it for human review or trigger a retry with a stricter prompt variant. For high-stakes domains like finance or healthcare, route all summaries through a human approval queue before display.

Log every step: the raw tool output, the prompt template with filled variables, the model's raw response, the validation result, and any retry attempts. Use structured logging with trace IDs so you can debug hallucination patterns and field extraction failures over time. For model choice, prefer models with strong instruction-following and low hallucination rates on structured data tasks. If the tool output exceeds the model's context window, preprocess it by extracting only the fields listed in the prompt's [RELEVANT_FIELDS] parameter before calling the model. Never truncate silently—always mark truncated content explicitly in the prompt input.