Find Event (Agent Tool)

Search past events so the agent can make decisions from user activity

How Find Event works

Find Event lets your agent query existing event data during a run. This is useful when the trigger event alone does not contain enough context to decide what action to take. The agent can look up any named event for the current user, apply filter conditions to narrow results, and choose whether to return the newest or oldest match. The returned event object — including its custom properties — becomes part of the agent’s working context for downstream tool calls and decisions.

Configuration

Inputs

Prompt · string

Guidance for when the agent should call this tool.

Event Name · string

The event to search for.

Query Conditions · object[]

Optional filter conditions to narrow matches.

Selection Strategy · enum · default: "newest"

Which matching event to return. Options: newest, oldest.

Outputs

event · object · required

The found event data that matches the search criteria.

Show Event Properties

event.event_name · string · required

The name of the found event.

event.timestamp · string · required

ISO 8601 timestamp of when the event occurred.

event.org_user_id · string · required

The user associated with the event.

event.custom_properties · object

Key-value map of custom data attached to the event at ingestion time.

event.source · string

Origin of the event (e.g. SDK, API, integration).

event.event_id · string

Unique identifier for the event record.

Use Cases

Behavior Analysis

Event Name: purchase_completed
Query Conditions: purchase_amount > 100
Selection Strategy: newest
Use: Personalize recommendations based on recent high-value purchases

Feature Usage Tracking

Event Name: feature_activated
Query Conditions: feature_name = "advanced_reporting"
Selection Strategy: newest
Use: Confirm feature adoption before sending upgrade prompts

Onboarding Progress

Event Name: onboarding_step_completed
Query Conditions: step_index >= 3
Selection Strategy: oldest
Use: Determine where a user stalled in the onboarding flow

Support Context Enrichment

Event Name: support_ticket_created
Query Conditions: priority = "high"
Selection Strategy: newest
Use: Give the agent recent support history before composing outreach

Best Practices

Efficient Queries

• Use specific event names rather than broad searches to keep lookups fast.
• Apply query conditions to filter irrelevant matches before they reach the agent.
• Prefer newest selection when recent behavior matters most; use oldest for first-occurrence analysis.

Context Utilization

• Combine event data with user properties for richer decision-making.
• Reference custom properties from the returned event in downstream tool prompts.
• Chain Find Event with other tools (e.g. Smart Message, Set Custom Property) so the agent acts on real activity data.

Data Management

• Ensure event names follow a consistent naming convention so the agent can reliably locate them.
• Keep custom property schemas stable across event versions to avoid unexpected nulls.
• Use query conditions as guardrails to prevent the agent from acting on stale or irrelevant events.