The tool message
After running the tool, you append the assistant's tool-call message and then a tool message with the result, linked by tool_call_id.
Last updated
Analogy
Replying in the right email thread. The tool_call_id is the In-Reply-To header, so the model knows which request this answers.
Code example
messages.push(message); // the assistant's tool_calls messagemessages.push({ role: "tool", tool_call_id: call.id, content: JSON.stringify(await getOrder(args)),});In an agent
Every tool result an agent sees arrives as one of these messages.
Practice
Flashcards
- What is tool (function) calling?The model asks your code to run a function with given arguments. Your code runs it and sends back the result.
- Interview: does the model run your tool?No. It returns the tool name and arguments; your code validates, runs it, and sends the result back as a tool message.
Interview questions
- How does function / tool calling work?
- Describe each tool with a name, a description and a JSON schema for its parameters.
- The model returns which tool to call and with what arguments. It never executes code itself.
- Your code validates the arguments, runs the function, and sends the result back as a tool message.
- The model then continues with the result in context.
Questions people ask
How do I send a tool result back to the model?
First append the assistant message that contained the tool_calls. Then append one message with role tool, the matching tool_call_id, and the result as a string, usually JSON. Call the model again with the updated messages. The id links each result to the request it answers.
What should a tool result contain?
Only what the model needs for its next step, as short JSON. Return a few useful fields rather than a whole API response, because every token in a tool result is paid for again on later steps. For failures, return a clear error message instead of throwing, so the agent can recover.