How to Build an AI Agent Stock Watchlist with Radar and Alerts

An AI stock watchlist becomes useful after it stops behaving like a list of tickers. The agent needs to answer questions about any covered stock, distinguish available facts from missing research, remember what the investor follows, and return only changes worth reviewing.

This guide describes that architecture using Stocksbrew Radar and agent access. It covers the domain model, MCP tools, REST endpoints, research states, cursor handling, alert permissions, and failure behavior needed for a dependable personal stock agent.

The smallest useful mental model

Ask about a stock
→ read what exists
→ show the research state
→ add to Radar with confirmation
→ queue research
→ check changes with a cursor
→ create alerts with confirmation

This is enough for a real workflow. A generic “stock action” tool would make permissions, confirmation, and audit logs harder to understand. Explicit tools let the agent discover the exact job and let the user grant only the relevant scope.

Use explicit tools for explicit jobs

A complete personal stock agent can use eleven Stocksbrew MCP tools:

• search_stocks
• get_stock_intelligence
• compare_stocks
• get_market_brief
• get_my_radar
• get_radar_changes
• add_to_radar
• remove_from_radar
• get_my_alerts
• create_alert
• delete_alert

The first four answer research questions. The next four manage the watchlist and incremental changes. The final three manage alert configuration. There are no brokerage or trading tools.

Make every supported stock answerable

The most common bad design is returning a hard error whenever a generated brief is absent. That makes the agent useless for newly discovered stocks. A better response returns the baseline record and a separate coverage object.

{
  "schema_version": "2026-08-01",
  "instrument": { "ticker": "CCL", "name": "Carnival" },
  "market_data": { "price": 27.81 },
  "coverage": {
    "status": "baseline_only",
    "tracked_in_radar": false,
    "has_baseline_data": true,
    "has_detailed_call": false,
    "has_pro_scores": true,
    "research_job": null,
    "next_action": {
      "action": "ask_to_add_to_radar",
      "tool": "add_to_radar"
    }
  }
}

The agent can answer from the factual baseline, label the missing brief, and ask whether the user wants deeper monitoring. This keeps a missing field from being mistaken for a negative signal.

Model generated research as state

Research generation is asynchronous and can fail. Treat it as a small state machine:

• baseline_only: factual stock data exists, detailed research does not.
• queued: the request was accepted.
• running: a worker is generating the brief.
• ready: detailed research can be used.
• no_sources: the system could not find enough usable source material.
• failed: processing failed and can be retried with confirmation.
• unavailable: the stock has no usable baseline record.

Return a machine-readable next_action with the state. The agent writes the conversational wording. The server remains the authority on what action is valid.

Make add-to-Radar idempotent

Agents retry. Networks time out. A user can ask twice. Adding a stock to Radar should not create duplicate rows or double-count the watchlist. The same action can safely refresh missing or failed research for an already tracked stock.

This avoids a separate “request research” tool and matches the human product: following the stock is the durable reason to spend work generating a brief.

Return changes instead of a repeated dashboard

A recurring agent should not narrate the full Radar every morning. get_radar_changes accepts a saved cursor and returns only attention items after that point.

{
  "attention_items": [
    {
      "item_id": "earnings:AMD:2026-08-01T09:00:00Z",
      "ticker": "AMD",
      "kind": "earnings",
      "occurred_at": "2026-08-01T09:00:00Z",
      "summary": "Earnings are due within 24 hours"
    }
  ],
  "cursor": "2026-08-01T09:00:00Z"
}

Treat the cursor as opaque. Persist it only after the summary or channel message succeeds. Keep item IDs for deduplication. Back off on HTTP 429 and transient 5xx errors.

Separate Radar changes from alert rules

Radar changes are an incremental read for earnings, RSI extremes, call changes, anomalies, news, and tracked price events. Custom email alert rules currently support price thresholds.

The agent should confirm the exact rule before writing:

User: Tell me when MSFT enters the buy zone.

Agent: I can create a price alert using the current zone threshold. Should I create that email alert?

After confirmation, return the alert ID and normalized configuration. Listing alerts should return active rules, not imply that it is a history of delivered notifications.

Design scopes around user intent

• stocks:read for stock search, intelligence, and comparison.
• market:read for the current market brief.
• radar:read for the member's watchlist and changes.
• radar:write for adding and removing tracked stocks.
• alerts:read for configured alert rules.
• alerts:write for creating and deactivating rules.

A research-only client does not need writes. A daily companion needs Radar read. A full assistant needs all six. Keep trading outside the system entirely.

Keep MCP and REST behavior aligned

MCP works well for conversational discovery. REST works well for deterministic scripts and clients without MCP support. Both should call the same domain operations and share validation, scopes, quotas, errors, and response field names.

REST parity prevents the research workflow from being locked to one model client. It also makes integrations easier to test with simple HTTP requests before introducing an agent.

Return recoverable errors

Use stable codes such as stock_not_found, invalid_alert_kind, email_required, profile_not_ready, forbidden_scope, subscription_required, and rate_limited. Include a retry delay when time can resolve the problem.

Do not use errors for normal research states. “Brief not generated” belongs in coverage. “Ticker does not exist” belongs in an error.

A practical daily prompt

Check my Stocksbrew Radar using the saved cursor. Tell me only what changed in earnings, directive, risk, or tracked price levels. For any stock with queued research, check whether it is ready. Do not change Radar or alerts without asking. Save the cursor only after this report succeeds.

This prompt has a bounded job, a factual source, a clear silence condition, and safe mutation rules. It is much easier to audit than “watch the market and tell me what matters.”

Production checklist

• Every response carries schema version, request ID, as-of time, freshness, usage, and notice fields.
• Missing research returns baseline data and coverage state.
• Radar mutations are idempotent and account counters remain atomic.
• Alert writes validate ticker, kind, threshold, condition, and ownership.
• OAuth grants are narrow, visible, refreshable, and revocable.
• Write tools are annotated and their descriptions require confirmation.
• Cursor persistence happens only after successful delivery.
• No tool can place a trade or access a brokerage.