Tool Output Schema Definition Prompt

Use this prompt when you are an integration developer or AI engineer who needs to define a strict, machine-readable contract for the data a tool returns to a model. The job-to-be-done is translating a raw API response, database query result, or function return value into a JSON Schema that the model can reliably parse, extract from, and summarize for an end user. This is not a prompt for writing the tool's business logic or its input parameters; it is specifically for shaping the output so that downstream model reasoning is grounded in known fields, types, and nullability rules. The ideal user is someone wiring a retrieval endpoint, a CRM lookup, or an internal service into an AI copilot or agent loop.

You should reach for this prompt when the tool's raw output is a nested, inconsistent, or overly verbose blob that causes the model to hallucinate fields, miss null values, or fabricate summary data. It is also appropriate when you are versioning an API and need the model to handle both old and new response shapes gracefully. Do not use this prompt for simple tools that return a single scalar value or a flat list of strings where the structure is self-evident. Avoid it when you need to define input schemas, tool selection logic, or error recovery strategies—those are separate playbooks. The prompt is most valuable when the output contract must be auditable, testable, and stable across model updates.

Before using this prompt, gather the raw output samples from your tool, including edge cases like empty result sets, partial failures, and deprecated fields. The prompt works best when you provide concrete examples of both the raw output and the desired structured output. After generating the schema, you must validate it against real tool responses and run eval checks for hallucinated fields and empty-result handling. If the tool's output can contain sensitive data, ensure the schema marks fields that require redaction or human review before they reach the user.

This prompt template is designed for integration developers who need to define a reliable contract for tool outputs. The goal is to produce a JSON Schema that downstream code can use for validation, ensuring that models extract and summarize results consistently. The prompt forces the model to act as a schema designer, considering field descriptions, types, nullability, and how to handle empty or partial results. Use this template when you have a clear understanding of the tool's purpose and the data it returns, but need a formal, machine-readable schema to enforce structure in your application.

textCopy
You are a precise API schema designer. Your task is to generate a strict JSON Schema that defines the expected output structure for a tool.

**Tool Name:** [TOOL_NAME]
**Tool Purpose:** [TOOL_PURPOSE]
**Raw Output Description:** [RAW_OUTPUT_DESCRIPTION]
**Context of Use:** The model will call this tool, receive a raw response, and then must extract and summarize the result for a user or another system. The schema you define will be used to validate the model's structured summary.

**Constraints:**
- The output must be a valid, single JSON Schema object (draft-07 or later).
- Every field must have a clear `description` explaining what it contains.
- Explicitly define which fields are required.
- For each field, specify its `type` and, if applicable, a `format`.
- Use `null` types explicitly for fields that can be absent or empty. Do not rely on optionality alone to signal missing data.
- Include a top-level field `[ERROR_FIELD_NAME]` of type `object` or `string` to capture tool-level errors, timeouts, or empty results. This field must be present in every response.
- Add a `[PARTIAL_RESULT_FLAG]` boolean field to indicate if the result is incomplete.
- For any enumerated values, provide the full `enum` list.
- Provide an `examples` array within the schema containing at least two valid JSON instances: one for a successful, complete result and one for an empty or error result.
- Do not include fields that the tool does not return. Do not hallucinate output fields.

**Output Format:**
Return only the JSON Schema object, enclosed in a ```json code block. Do not add any explanatory text outside the code block.

To adapt this template, replace the placeholders with specifics from your tool's implementation. [TOOL_NAME] should be the exact function name the model uses. [TOOL_PURPOSE] is a one-line description of what the tool does, which helps the schema designer understand the context. [RAW_OUTPUT_DESCRIPTION] is critical; describe the raw API response or data structure the tool returns, including its format (e.g., a nested JSON object from a REST API, a CSV string, or a simple status code). Customize [ERROR_FIELD_NAME] and [PARTIAL_RESULT_FLAG] to match your application's error-handling conventions. After generating the schema, you must validate it programmatically against actual tool outputs and model-generated summaries to ensure it is neither too permissive nor too strict. A common failure mode is a schema that is technically valid but fails to capture the semantic meaning of an empty result, leading to hallucinated data downstream.

This prompt is designed to be called programmatically as part of a tool registration pipeline, not as a one-off chat interaction. The primary integration point is immediately after a developer defines a new tool's function signature and before that tool is registered in the model's tool catalog. The application should take the raw API response, function description, or database schema as the [TOOL_DESCRIPTION] input, call the model with this prompt, and parse the resulting JSON Schema output. Store the generated output schema alongside the tool definition in your tool registry so that every tool call result can be validated against its contract before being passed back to the model or displayed to a user.

Implement a validation layer that checks the generated schema for required fields: type must be 'object', properties must be a non-empty object, and every property must have a type and description. Reject schemas that contain properties not present in the tool's documented return payload—this is the primary hallucination vector. For nullable fields, enforce that the schema uses an explicit `

type": ["string

null