eodhd-screen

name	eodhd-screen
description	Screen stocks by fundamental and technical criteria using the EODHD screener — market cap, P/E, dividend yield, sector, exchange, and signals, with currency- aware thresholds. Invoke as /eodhd-screen <criteria>.
argument-hint	<criteria, e.g. high dividend large cap US>

Screen stocks using EODHD screener based on these criteria: $ARGUMENTS

Translate the user's criteria into EODHD screener filters.

Filter format (critical): filters is a JSON array of [field, operation, value] triples, NOT dot-notation and NOT a JSON object. A JSON object is rejected with HTTP 422 ("must be an array"). Operations: =, !=, >, >=, <, <=, match.

Sort format: --sort field.direction, e.g. market_capitalization.desc or pe.asc. A bare field name (or a separate order flag) is rejected with HTTP 422 ("sort.0.direction is required").

Currency caveat (important): absolute-money fields — market_capitalization, revenue, ebitda — are reported in each listing's local currency, not normalized to USD. So a raw threshold leaks huge non-USD companies (e.g. a Vietnam-listed firm shows "3.88T" ₫ ≈ $150M but passes a >= 10B filter). Each result row carries a currency_symbol field telling you the currency. Therefore:

• When filtering/sorting by an absolute-money field, scope to one market — add ["exchange","=","us"] (or the user's intended exchange) so the threshold is currency-consistent.
• For multi-market screens, you cannot compare raw caps across rows — group/label by currency_symbol.
• Ratio/percent fields (pe, pb, ps, peg, roe, roa, beta, dividend_yield) are currency-independent and safe to compare across markets.

Instrument-type noise (important — the screener has NO type filter): there is no field to restrict results to common stock. Passing ["type", ...] is rejected with HTTP 422 (filters.0.field is invalid). Two kinds of junk leak into unscoped screens, especially dividend screens:

• OTC / foreign cross-listings — the combined ["exchange","=","us"] virtual exchange includes OTC grey-market listings (codes ending in F/Y, e.g. TCANF, RNECF) with broken dividend_yield (55–110%). Scope to a real venue instead — ["exchange","=","nyse"] or ["exchange","=","nasdaq"] — to drop them. (us is still fine when you only need currency consistency, not clean common stock.)
• Preferred shares / baby bonds — these list on NYSE/NASDAQ too, carry a - in code (e.g. JPM-PD, DLR-PJ) and a coupon rate in name, and dominate high-yield screens. The API can't filter them, so post-filter the results: for a common-stock screen, drop rows whose code contains -.
• Sanity-cap broken yields — for any dividend screen add ["dividend_yield","<=",0.25] (no real common stock yields >25%) to discard rows with corrupt data.

Common mappings (note: dividend_yield is a fraction — 0.03 = 3%):

• "large cap" → ["market_capitalization",">=",10000000000]
• "mid cap" → ["market_capitalization",">=",2000000000],["market_capitalization","<=",10000000000]
• "small cap" → ["market_capitalization","<=",2000000000]
• "high dividend" → ["dividend_yield",">=",0.03],["dividend_yield","<=",0.25] (upper cap drops broken-data OTC/preferred rows)
• "low P/E" or "cheap" → ["pe",">",0],["pe","<",15] + --sort pe.asc
• "tech" → ["sector","=","Technology"]
• "healthcare" → ["sector","=","Healthcare"]
• US stocks → ["exchange","=","nyse"] or ["exchange","=","nasdaq"] for clean common stock (avoids OTC junk); use ["exchange","=","us"] only when you need currency consistency, not a clean instrument set
• Sector names, industry names, exchange codes as additional [field,"=",value] triples

Example: "high dividend large cap (US)" → --filters '[["dividend_yield",">=",0.03],["dividend_yield","<=",0.25],["market_capitalization",">=",10000000000],["exchange","=","nyse"]]' --sort dividend_yield.desc (then drop result rows whose code contains - — those are preferred shares, not common stock)

Use the stock-screener skill workflow:

1. Run screener with translated filters (limit 20)
2. Unless the user explicitly wants preferred shares/ETFs, drop result rows whose code contains - (preferred shares) before presenting — the API has no instrument-type filter to do this server-side
3. For top 5-10 results, fetch fundamentals for deeper detail
4. Fetch recent price data for performance context

Present:

• Filters Applied — show the JSON filter used
• Results Table — ticker, name, sector, market cap (with its currency_symbol), P/E, dividend yield, price, 30d change. Show the currency next to any cap/revenue figure; never present a non-USD cap as if it were USD.
• Top 5 Deep Dive — expanded valuation and growth metrics for best matches
• Summary — key themes and patterns in results

If criteria are vague, ask for clarification or suggest reasonable defaults.

Include disclaimer: "This is not financial advice. Data is for informational purposes only."