WatchList Tool

What is it?

The WatchList Tool lets you create proactive, recurring monitors on volatile external data — stock prices, weather, news, web pages, APIs, horoscopes, or even recurring AI queries. Instead of checking manually, you set a trigger condition and Yukkai notifies you the moment it's met.

Think of it as a standing alert: "Tell me when AAPL drops below $170" or "Notify me every morning at 8 AM with today's horoscope." Once created, the watch runs in the background at the frequency you specify.

WatchList vs. Scheduling: Use WatchList for ongoing monitoring of changing external data. For one-time future reminders or scheduled prompts, use the Scheduling tool instead.

How it works

Each watch has five core components:

Component	Description
Source	Where the data comes from — a web page, an API, a local provider, or an LLM query
Category	What kind of data: horoscope, stock, weather, news, webPage, api, local, custom
Trigger	The condition that fires a notification — a value threshold, a daily time, a change, new items, or matching text
Frequency	How often Yukkai checks the source (minimum every 5 minutes)
Limits	Maximum notifications per day to prevent spam

When Yukkai checks a watch, it fetches the latest data from the source, evaluates the trigger, and sends you a notification only if the condition is met.

Trigger types

Trigger	What it does	Example
dailyAt	Fires once at a specific hour	Daily horoscope at 8 AM
valueChanged	Fires when the monitored value changes	Stock price moved
percentChange	Fires when the value changes by a percentage	Crypto dropped 5%+
newItemsDetected	Fires when new items appear	New news article published
contains	Fires when the source contains specific text	Web page mentions "sold out"
threshold	Fires when a value crosses a threshold	AAPL below $170

Each trigger type has a sensible default frequency and max-per-day — you only need to override them when you want something specific.

How to use it

You manage watches through five actions:

• Create — Set up a new watch with a source, trigger, and notification preferences.
• List — View all active watches and their current state.
• Update — Modify an existing watch (enable/disable, change frequency, adjust limits).
• Delete — Remove a watch you no longer need.
• Run — Force an immediate check of any watch, regardless of its schedule.

Creating a watch

When creating a watch, you need:

1. A category (what kind of data to monitor)
2. A source type and source URL or prompt (where the data lives)
3. A trigger and trigger value (when to notify you)
4. A title and query (human-readable description)

Optional parameters like frequency_minutes and max_per_day let you fine-tune the behavior.

Examples

Example 1: Stock price alert

"Notify me when AAPL drops below $170."

• Category: stock
• Source type: webPage (or api if you have a stock API)
• Source URL: a financial data page
• Trigger: threshold
• Trigger value: 170 (with direction below)
• Frequency: every 30 minutes

Example 2: Daily horoscope

"Send me my horoscope every morning at 8 AM."

• Category: horoscope
• Source type: llmQuery
• Source prompt: "Generate today's horoscope for Virgo"
• Trigger: dailyAt
• Trigger value: 8 (8 AM)

Example 3: Web page change monitoring

"Tell me when this product page says 'in stock'."

• Category: webPage
• Source type: webPage
• Source URL: the product page URL
• Trigger: contains
• Trigger value: in stock
• Frequency: every 15 minutes

Example 4: News monitoring

"Notify me when new articles about Tesla appear."

• Category: news
• Source type: webPage or api
• Trigger: newItemsDetected
• Frequency: every 60 minutes

Tips & best practices

• Start with defaults — Each trigger type ships with sensible frequency and daily limits. Only override when you have a specific need.
• Use run to test — After creating a watch, use the run action to trigger an immediate check. This confirms the watch is working before you wait for the next scheduled cycle.
• Mind the 5-minute floor — WatchList checks data at least every 5 minutes. For real-time needs (sub-minute), consider a different approach.
• Prevent notification spam — Set max_per_day to cap how many alerts you receive. A watch that fires too often becomes noise.
• Clean up stale watches — Use list periodically to review your active watches and delete ones you no longer need.
• Combine with categories — The category field helps Yukkai understand the data context, so always pick the most accurate one (stock vs custom makes a difference in how the source is interpreted).
• Use valueChanged for broad awareness — If you just want to know something changed (not a specific threshold), valueChanged is the simplest trigger.