Action guide
Record the result of every tool call back to the agent
POST
/v1/events · agent.tool_returnedEmit an `agent.tool_returned` event right after a tool finishes, before handing control back to the model. Stores the result status (success or failure), the duration and any error. Critical for diagnosing slow or flaky tools that derail an agent.
When to emit
Inside your tool dispatcher, immediately after the tool function resolves or rejects, before pushing the result back into the conversation.
Example payload
await recalled.events.create({
action: "agent.tool_returned",
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 | Same user id as the matching agent.tool_called event |
conversation_id | Same conversation id as the matching call |
tool_call_id | Same tool_call_id as the matching call, used to pair them |
tool_name | Name of the tool that just returned |
result | success or failure |
duration_ms | How long the tool took to run, in milliseconds |
error | Error message and code if result is failure |
Suggested retention
Keep for at least 3 months. Useful for debugging timeouts and tool-side errors.