Action guide
Record every tool invocation your agent makes
POST
/v1/events · agent.tool_calledEmit an `agent.tool_called` event the moment your AI agent decides to invoke a tool, before the tool runs. Captures the agent identity, the tool name, the arguments and the user who triggered the conversation. Pairs with `agent.tool_returned` for full traceability.
When to emit
Right after the model returns a tool_use block and your wrapper extracts the tool name and arguments, before the actual tool function runs.
Example payload
await recalled.events.create({
action: "agent.tool_called",
actor: { id: user.id, email: user.email },
organization: user.organizationId,
metadata: {
triggered_by_user: "value",
conversation_id: "value",
tool_call_id: "value"
},
});Metadata to include
Keep metadata flat and consistent across your service so it plays well with search and CSV exports.
| Key | Purpose |
|---|---|
triggered_by_user | Internal id of the human user who started the conversation |
conversation_id | Your conversation or session id, ties this event to the chat |
tool_call_id | Provider tool_call_id (Anthropic, OpenAI), useful for replays |
tool_name | Name of the tool the agent decided to call |
tool_args | Arguments the agent passed to the tool |
model | Model id, e.g. claude-sonnet-4.6 |
reasoning | Optional short reasoning string when the model exposes one |
Suggested retention
Keep for at least 6 months. Useful for replaying agent decisions when a user disputes a tool call.