Skip to content
Telemetry
AI agent security

agent_tool_authorization_decided event schema

Record the policy decision before an agent calls a tool that can change data or take action. Use approved tool, risk, decision, and policy values. Exclude prompts, arguments, results, credentials, and customer content.

Reviewed by the Telemetry product team on . We checked what each event represents, which service sends it, field types, sensitive data, the example, and validation steps. Who reviews this page

Test this schema

Question this event answers

Which agent tool actions are allowed, denied, or routed to human approval?

Fields
12
Required
12
Send and check an event

Record and query agent_tool_authorization_decided

Document what each agent_tool_authorization_decided row represents and which service sends it. Send test events to check the fields, then verify that the query answers your question.

  1. 1

    Outcome becomes final

    Agent authorization or policy-enforcement layer emits only after policy evaluation is final and before the tool is allowed to execute.

  2. 2

    Choose the fields

    12 required fields preserve the declared grain: One final authorization decision per logical tool-call attempt.

  3. 3

    Check the test event

    Check types, UTC time, alternate outcomes, idempotency, and every pseudonymous or review-classified field.

  4. 4

    Query the result

    Which agent tool actions are allowed, denied, or routed to human approval?

Grain

One final authorization decision per logical tool-call attempt.

Owner

Agent authorization or policy-enforcement layer

Emit when

After policy evaluation is final and before the tool is allowed to execute.

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.

FieldTypeRequiredPrivacyMeaning
timestamp_utctimestampyesnon-sensitiveUTC time when the operation finishes.
event_idstringyesnon-sensitiveStable unique identifier used for deduplication.
releasestringyesnon-sensitiveApplication or service version that emitted the event.
account_idstringyespseudonymousStable internal account identifier, never an email or name.
run_idstringyespseudonymousStable agent-run identifier shared with approved outcome events.
tool_call_idstringyespseudonymousStable identifier for the logical tool-call attempt; never embed arguments.
workflowstringyesnon-sensitiveVersioned, low-cardinality agent workflow.
tool_namestringyesnon-sensitiveApproved low-cardinality tool identifier.
risk_levelstringyesnon-sensitiveReviewed risk class such as low, medium, or high.
decisionstringyesnon-sensitiveAllowed, denied, or approval_required.
reason_codestringyesnon-sensitiveControlled policy reason; never a free-form model explanation.
policy_versionstringyesnon-sensitiveVersion of the policy contract that made the decision.

Synthetic JSON event

{
  "timestamp_utc": "2026-07-30T16:24:12Z",
  "event_id": "evt_agent_authz_01",
  "account_id": "acct_8f31",
  "release": "2026.07.4",
  "run_id": "run_f28c",
  "tool_call_id": "tool_call_a913",
  "workflow": "support_resolution_v3",
  "tool_name": "database_write",
  "risk_level": "high",
  "decision": "approval_required",
  "reason_code": "external_state_change",
  "policy_version": "agent-policy-12"
}

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: pseudonymous
  • run_id: pseudonymous
  • tool_call_id: pseudonymous

Validation checklist

Test the schema before building a dashboard

  • Send one known agent_tool_authorization_decided fixture after the documented outcome boundary.
  • Verify all 12 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_authorization_decided before agent authorization or policy-enforcement layer 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

AI agent security SQLAI agent security guideAI agent security templateEvent schema design guide

Related contracts

user_signed_up

Which signup cohorts activate and retain?

Review schemaproduct_milestone_completed

Which accounts complete the milestones you use to define activation?

Review schemaapi_request_completed

Where do errors and slow requests affect customers?

Review schema

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.

Test this schema