# 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.

AI developers · Part 03: Tool calling · Card 6 of 10 · Last updated 2026-10-13

## 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

`tool-result.ts`

```typescript
messages.push(message); // the assistant's tool_calls message
messages.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.

## Related concepts

- [The tool_calls reply](https://studyvisually.com/learn/tech/ai-developers/tool-calling/tool-calls-response)
- [What a tool is](https://studyvisually.com/learn/tech/ai-developers/tool-calling/what-a-tool-is)
- [Validate tool arguments](https://studyvisually.com/learn/tech/ai-developers/production/validate-tool-arguments)
- [Function schema](https://studyvisually.com/learn/tech/ai-developers/tool-calling/function-schema)

Web page: https://studyvisually.com/learn/tech/ai-developers/tool-calling/tool-message
Study this card in the app: https://studyvisually.com/app/learn?category=ai-developers&card=tool-message