Monitoring recipe

What to keep between runs

• The watchlist: up to 50 tickers per list_recent_filings call.
• The set of accession numbers you have already processed.

Each run

1. 1. Poll

   One call covers the whole watchlist. Optionally narrow with form_types, or form_subtypes=["8-K-earnings"] (which implies 8-K only). Foreign issuers file 6-K, 20-F and 40-F; add those to form_types if your watchlist has any.

   list_recent_filings(tickers=["NVDA", "MSFT", "CLF"], since="<today minus 30 days>", limit=100)

2. 2. Dedupe by accession

   Skip every row whose accession you already processed. Do not use the last poll's date as the next since: a filing appears only once MetricDuck has extracted its text, and a small share (mostly 8-K and 6-K exhibits) is extracted days or weeks after its SEC filing date. A 30-day lookback with dedupe catches them.

3. 3. Check the row count

   Rows are newest first. If a poll returns limit rows, older rows may have been cut: split the watchlist or narrow form_types.

4. 4. Act on each new filing

   8-K earnings release (form_subtype 8-K-earnings)

   The headline figures with receipts, the guidance text, and the next scheduled call.

   get_earnings(ticker="CLF", quarters=2)
   get_filing_section(ticker="CLF", accession_number="<row accession>",
                      section_id="earnings_press_release", query="outlook")
   get_company_events(ticker="CLF")

   Other 8-K (8-K-event, 8-K-other) or 6-K

   Without section_id the reply is the filing's outline; then read the section you need.

   get_filing_section(ticker="CLF", accession_number="<row accession>")

   10-Q or 10-K

   What matters in the new filing (get_filing_index indexes the latest one), then the numbers.

   get_filing_index(ticker="CLF")
   get_financials(ticker="CLF", period="quarterly", years=1)

   Flags since the last run

   Signals that fired for the company between the last run and today.

   screen_filing_signals(signals=["earnings_guidance_lowered_8k", "tone_cautious", "covenant_risk"],
                         ticker="CLF", match_mode="any",
                         since_date="<last run date>", until_date="<today>")

5. 5. Record the accession once the filing is processed.

Schedule it

cron or any scheduler

Run your agent on a schedule with MetricDuck configured with an API key (Authorization: Bearer fda_…; the setup guide has the config). Store the processed accessions between runs.

Claude Code routine

Create a scheduled routine (/schedule in Claude Code, or claude.ai/code/routines), paste the steps above as its prompt with your watchlist, and connect the channel the result should go to.

MCP setup guide →

Quota maths

Free: 500 tool calls/day (resets 00:00 UTC). Pro: no daily cap (50,000 tool calls/month). One MCP tool call is one tool call, however much work it does behind the scenes.

• One poll is one tool call, whatever the watchlist size (up to 50 tickers).
• Polling every 30 minutes is 48 tool calls a day; hourly is 24; every 5 minutes is 288.
• Each new filing costs about 2 to 4 more calls (an earnings 8-K with every call above: 4).
• Example: 50 tickers polled every 30 minutes (48) plus a busy earnings day with 15 new filings at 4 calls each (60) is 108 tool calls, about 22% of the Free day. In quiet weeks the poll is most of the cost.
• At the cap, every tool returns a 429 until 00:00 UTC. The next run catches up, because the lookback and the dedupe do not depend on the last run succeeding.