OpenAI Responses output_text: Read Museum Label Drafts Without Mistaking a Tool Call for Final Text

The gallery label that disappears behind a response item

A museum assistant drafts a short exhibit label from curator-approved notes. The application developer reads response.output[0].content[0].text and assumes the first output item must be the final visitor-facing sentence. That assumption can break when a model uses a tool, produces a reasoning-related item, or returns a different typed structure before its assistant message. The application may show a blank label or, worse, mishandle a non-text item as if it were approved prose. OpenAI documents Responses as an array of typed output items rather than a fixed first-message slot. This scenario is hypothetical and does not describe an observed model run or a real museum publication.

Understand what the Responses output array holds

The Responses API object contains an output array whose length and order depend on the response. Items can include assistant messages and tool calls, and the model may generate other item types. A message contains content items that themselves have types, such as output_text. Therefore, the path to final prose is not universally the first array element and first content element. OpenAI’s text guide explicitly warns against assuming output[0].content[0].text. Treat output as a sequence that needs type-aware interpretation, just as you would handle different event types in an application protocol. Do not infer text availability solely from the presence of at least one output item.

Use output_text as a convenience, not a completion gate

Some official OpenAI SDKs offer a response.output_text helper that combines text output into a convenient string. This can be appropriate when a completed response is known to contain ordinary prose and the application only needs that prose for a review queue. The helper does not execute pending tool calls, approve a museum label, or validate its factual assertions. Not every client environment exposes exactly the same convenience property, so check the SDK version and supported interface. A missing or empty aggregate text value is an application state that needs examination, not permission to invent a fallback answer. The process diagram separates response inspection, item parsing, and editorial review.

Inspect completion and non-text outcomes separately

Before treating any generated string as final, check the response’s documented status and applicable incomplete or error details. A response can be unfinished, interrupted, or require additional action through a tool workflow. Also handle refusal-related content as a distinct outcome rather than rendering a generic success banner. The precise fields to inspect depend on the API response and library used; write code against the official typed definitions instead of guessing object layouts. A model can produce fluent text that still requires citation checks or human approval, so completion at the API level is necessary for the integration but never sufficient for a public conservation claim.

Do not mistake a function call for the final label

If a configured function is called, that output item contains the tool request rather than the desired gallery caption. OpenAI’s function-calling guide describes a loop in which the application receives a call, runs authorized code, returns a function_call_output linked with call_id, and then obtains a later model response. Some turns may include multiple calls. A tool request is not evidence that its requested database query actually ran or returned valid findings. Only the application can execute its own tool and attach the corresponding outcome. Do not stringify tool arguments and present them to visitors as the answer. The comparison illustration shows incorrect positional extraction versus type-aware handling, not actual API traffic.

Build a parser that matches the application contract

For a museum-label workflow, decide in advance which typed items are expected: perhaps a completed assistant message with plain text and, when enabled, one or more read-only catalog lookup calls. Walk output items by their type and collect only the fields the application intends to display. Treat unexpected item types as logged integration conditions, not as text to concatenate blindly. If the program supports an SDK output_text helper, verify that it behaves as intended for your message types. Keep tool calls and user-visible text in separate data models. This avoids an accidental display of internal arguments, reasoning metadata, or a partial state in the publication interface.

Validate sources and publication rights outside the parser

Correct text extraction says only that the application found generated text. It does not confirm that an object’s accession number is right, that a date is documented, or that a photograph may be shown publicly. Match every factual label claim against curatorial records and approved citations. Keep the answer in a draft state until the museum’s normal approval process is complete. Refusal handling and response status are also independent from a human review outcome. A rich, correctly typed output can still contain unsupported facts; a badly parsed output can conceal an otherwise useful answer. Both failure classes deserve tests. The parser is a transport and data-shaping component, not a fact-checking tool.

Test non-text, mixed, and incomplete responses

Construct controlled response fixtures for unit tests rather than assuming the happy path. Include an ordinary single text message, an array with a tool call before the message, multiple assistant content items, a refusal-like response, and an incomplete response lacking publishable prose. Verify that display text appears only in the intended cases and that the workflow requests human action when it cannot establish completion. Ensure no tool is executed from arbitrary untrusted JSON outside the explicitly authorized function loop. If SDK updates change item types or helpers, rerun these fixtures. A single successful demo with one text-only response does not demonstrate robustness across the full API contract.

Show staff clear states instead of a blank answer

For the review interface, expose meaningful application states such as “waiting for catalog lookup,” “draft ready for curator review,” or “generation incomplete.” These are labels for internal workflow status, not asserted outputs from a model. Keep a safe diagnostic correlation identifier so engineers can trace malformed responses without exposing private collection notes in ordinary logs. Record the model and SDK version relevant to each integration test and consult updated OpenAI documentation before migrating. The desired result is a stable bridge from typed API response to a reviewable museum-label draft, without confusing message order, tool execution, and editorial approval. A blank output_text should trigger investigation, never silent publication.

Related guides

• OpenAI Responses text.format: Draft Museum Labels as Reviewable JSON, Not Approved Facts
• OpenAI Responses text.verbosity: Shorten Museum Labels Without Deleting Safety Facts
• OpenAI Responses max_output_tokens: Stop a Cut-Off Museum Safety Notice From Going Live
• OpenAI Structured Outputs Refusal Handling: Do Not Turn an Unanswered Form Into an Approval

How We Research

We used these primary official sources: OpenAI text generation guide; OpenAI Responses API migration guide; OpenAI function calling guide; OpenAI Responses create reference. We read the OpenAI text generation guide, the Responses API migration guide, the function calling guide, and the Responses create reference to distinguish typed output items from SDK convenience text access and tool orchestration. No API calls were sent, tool outputs executed, or museum labels evaluated. Schematics are pedagogical abstractions, not service screenshots or live results. Readers should check current vendor documentation and their own security, pricing, and deployment settings. The drawings are explanatory, not reproductions of a vendor interface or evidence of live results.

Frequently Asked Questions