A clerk-of-courts docket assistant executes a records-lookup tool that the model requested. In the Messages API, how are the results of that tool returned to the model on the next request?
Select an answer to reveal the explanation.
Short Explanation
It feels backwards: the model asked for the docket lookup, so surely the answer is the assistant's. But the caller is always the user role, and tool output is what the caller supplies.
Full Explanation
Roles in the Messages API describe who supplied a piece of content, not who wanted it. The model produces assistant turns; the application produces user turns. Tool output is produced by the application, so it travels in a user turn even though the model is what requested it.
The assistant turn carrying tool_use blocks is answered by a user-role message whose content array holds the matching tool_result blocks. For a clerk-of-courts orchestrator this fixes the shape of the whole loop—execute the records lookup, wrap each output in a tool_result keyed to its tool_use_id, place them in a user message, and re-send the conversation so the model can fold the docket data into its answer.
The system prompt is a separate top-level parameter for standing instructions and is not part of the per-turn message exchange. Putting tool_result blocks in an assistant message attributes application-supplied data to the model and breaks the alternation required after a tool_use turn. There is no top-level tool_results field—tools are declared in the tools parameter, but their outputs travel inside the messages array as content blocks.
Exam caveat: this user-role turn is a protocol construct, not something a person typed—never render it back to court staff as conversation. Operational check: dump the outgoing messages array before a follow-up call and confirm the tool_result blocks sit in a user-role entry immediately after the assistant turn that requested them.