Record and query agent_tool_call_completed
Document what each agent_tool_call_completed row represents and which service sends it. Send test events to check the fields, then verify that the query answers your question.
- 1
Outcome becomes final
Agent runtime or tool-execution adapter emits only after the tool returns, times out, is denied, or fails for the current attempt.
- 2
Choose the fields
10 required fields preserve the declared grain: One completed tool-call attempt within an agent run.
- 3
Check the test event
Check types, UTC time, alternate outcomes, idempotency, and every pseudonymous or review-classified field.
- 4
Query the result
Which tools fail, retry, loop, or add latency before an agent reaches a useful outcome?
Grain
One completed tool-call attempt within an agent run.
Owner
Agent runtime or tool-execution adapter
Emit when
After the tool returns, times out, is denied, or fails for the current attempt.
Field contract
Field types and data to exclude
Keep field names and types stable once production queries depend on them. Document optional fields and add them only when they answer a specific question.
| Field | Type | Required | Privacy | Meaning |
|---|---|---|---|---|
| timestamp_utc | timestamp | yes | non-sensitive | UTC time when the operation finishes. |
| event_id | string | yes | non-sensitive | Stable unique identifier used for deduplication. |
| release | string | yes | non-sensitive | Application or service version that emitted the event. |
| account_id | string | yes | pseudonymous | Stable internal account identifier, never an email or name. |
| run_id | string | yes | pseudonymous | Approved identifier for the owning agent run. |
| tool_call_id | string | yes | pseudonymous | Stable identifier for this logical tool call. |
| tool_name | string | yes | non-sensitive | Allowlisted low-cardinality tool name. |
| status | string | yes | non-sensitive | Success, failed, timed_out, or denied. |
| attempt | number | yes | non-sensitive | One-based attempt number for the logical call. |
| duration_ms | number | yes | non-sensitive | Tool-call duration in milliseconds. |
| error_type | string | no | non-sensitive | Controlled failure category without exception text. |
Synthetic JSON event
{
"timestamp_utc": "2026-07-29T10:04:11Z",
"event_id": "evt_tool_01",
"account_id": "acct_8f31",
"release": "2026.07.3",
"run_id": "run_43fc",
"tool_call_id": "call_017",
"tool_name": "customer_lookup",
"status": "success",
"attempt": 1,
"duration_ms": 284
}Privacy review
Review identifiers before ingestion
This example uses synthetic identifiers. Pseudonymous values can still be personal data, and review fields can expose business or provider context. Apply your own consent, retention, access, residency, and deletion requirements.
account_id: pseudonymousrun_id: pseudonymoustool_call_id: pseudonymous
Validation checklist
Test the schema before building a dashboard
- Send one known agent_tool_call_completed fixture after the documented outcome boundary.
- Verify all 10 required fields arrive with the documented types.
- Retry the same event identifier and confirm the chosen deduplication behavior.
- Send a controlled failure or alternate outcome when the workflow supports one.
- Run the related SQL over a fixed window and reconcile the result to the fixture.
Common mistakes
Record one result per row
- Emitting agent_tool_call_completed before agent runtime or tool-execution adapter knows the final outcome.
- Mixing different kinds of results in one table, which makes counts and rates ambiguous.
- Replacing controlled categories with raw URLs, payloads, prompts, or error text.
- Changing a field type in place after saved queries and dashboards depend on it.
- Adding identifiers without a documented investigation, access, and retention need.
Use the contract
Query the event and set up monitoring
Related contracts
Send a test event before production traffic
Create a free API key, send the synthetic event, and inspect the inferred table before connecting a live workflow.