discovery
Find market-wide lists, screeners, calendars, filings, insider trades, and news for stocks, ETFs, indices, currencies, commodities, and crypto without tickers or countries.
Instructions
Market discovery (lists of stocks, ETFs, indices, currencies, commodities and cryptocurrencies, stock screener, biggest gainers and losers, most active stocks, sector and industry performance and P/E, earnings, IPO and stock split calendars, latest 8-K filings, insider trades and mergers, market news and press releases). No tickers or countries needed. The news and press release feeds (get_stock_news, get_press_releases, get_general_news, get_crypto_news, get_forex_news) are the latest articles across the whole market, not news about one company: each article names its ticker, but the feed cannot be narrowed to a ticker. The calendars and filings take start_date/end_date; the market-wide earnings calendar (get_earnings_calendar) covers the coming week unless a range is given and lists the largest companies first, one row per company (its primary, most traded listing; share classes with names of their own count as separate companies) with 'Market Cap (USD)'; min_market_cap= (in US dollars), country= (the company's country) and exchange= (e.g. 'XETRA') narrow it, sort_by='date' sorts by date and primary_only=false shows every listing. Its EPS and revenue are in the currency the source reports for each listing. Sector and industry performance and P/E take date= for one day's snapshot or sector=/industry= for a history (the last year unless start_date/end_date say otherwise); they average the companies of one exchange, exchange='NASDAQ' (default), 'NYSE' or 'AMEX', and performance is a decimal change (0.0125 is +1.25%). The stock screener ranks by market cap in US dollars ('Market Cap (USD)'; 'Market Cap' is in the listing's own currency) and returns every listing of a company unless primary_only=true; to screen by classification, use the Finance Database server. get_index_constituents lists the members of index='S&P 500', 'NASDAQ 100' or 'Dow Jones', today's or, with date=, those on a past date (with the date each left the index), free of survivorship bias; get_index_constituent_changes lists the dated additions and removals with their reasons (start_date/end_date). get_industry_statistics returns Aswath Damodaran's industry averages (about 95 industries plus the Total Market, computed every January from all listed companies): dataset='cost_of_capital' (default; beta, cost of equity and debt, debt weights, WACC), 'betas' (levered and unlevered betas, the unlevered beta corrected for cash, D/E ratio), 'total_betas', 'margins', 'price_to_earnings', 'price_to_book', 'price_to_sales' or 'enterprise_value_multiples', for region='United States' (default), 'Europe', 'Japan', 'Australia, New Zealand and Canada', 'Emerging Markets', 'China', 'India' or 'Global'; rates and margins are decimals, betas and multiples plain numbers. Use show_columns to keep a few columns.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"indicator": "<indicator>"
},
"name": "discovery"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | For get_index_constituents: The date (YYYY-MM-DD) to list the members of. A change takes effect on its own date, so the members on a change's date include it. For get_industry_pe, get_industry_performance, get_sector_pe, get_sector_performance: The date to retrieve a snapshot for, e.g. "2024-02-01". For get_insider_trading_latest: Only return the trades filed on this date. | |
| page | No | For get_delisted_stocks: The page of results to retrieve, starting at 0. For get_insider_trading_latest, get_mergers_acquisitions_latest, get_sec_filings_8k: The page number to retrieve. | |
| rank | No | true ranks the tickers (or countries) within every period, from the highest value (rank 1) to the lowest, and compares each with its neighbour toward the middle of the ranking: the Difference (in points for returns) and the Multiple (only when both have the same sign), so the first and last rank show how far the best and the worst stand apart, e.g. a fall more than twice as large as the next one. Needs a value per period and ticker; pick one field with show_columns where there are more. | |
| index | No | "S&P 500", "NASDAQ 100" or "Dow Jones". | S&P 500 |
| limit | No | The rows to return, like head and tail: 5 for the first five, -5 for the last five (the most recent of a time series). A table with its periods as columns (financial statements, ratios) keeps its first or last periods instead, and rows per ticker (an earnings calendar) are selected per ticker. For ETF holdings the largest (or, negative, the smallest) by weight, and for a list (e.g. news or a screener) its length. 0 returns every row. Leave unset to use the default of the indicator you selected. Defaults are 100 for get_crypto_news, get_delisted_stocks, get_forex_news, get_general_news, get_insider_trading_latest, get_mergers_acquisitions_latest, get_press_releases, get_sec_filings_8k, get_stock_news; 1000 for get_stock_screener. | |
| pages | No | The number of pages to collect, each page is a separate API call, e.g. pages=5 makes 5 calls. | |
| is_etf | No | Whether to restrict the screen to ETFs or to exclude them. | |
| region | No | The region: "United States", "Europe", "Japan", "Australia, New Zealand and Canada", "Emerging Markets", "China", "India" or "Global". | United States |
| sector | No | For get_sector_pe, get_sector_performance: The sector to retrieve the history for, e.g. "Energy". For get_stock_screener: The sector to restrict the screen to, e.g. "Energy". | |
| country | No | For get_earnings_calendar: The country of the company, as a two-letter code ("DE") or a name ("Germany"). It is looked up with the company screener, which returns at most 10,000 listings, largest first, so for the United States without a min_market_cap the smallest companies can be missing. For get_stock_screener: The country to restrict the screen to, as a two-letter code ("US") or a name ("United States"). | |
| dataset | No | The dataset: "betas", "total_betas", "cost_of_capital", "margins", "price_to_earnings", "price_to_book", "price_to_sales" or "enterprise_value_multiples". | cost_of_capital |
| sort_by | No | "date" to sort by date and symbol, or "market_cap" to put the largest companies first. Leave unset to use the default of the indicator you selected. Defaults are 'market_cap' for get_earnings_calendar. | |
| end_date | No | End of the date range in YYYY-MM-DD format; left empty, today (or the indicator's own window). | |
| exchange | No | For get_earnings_calendar: The exchange code of the listing, such as "NASDAQ" or "XETRA". For get_industry_pe, get_industry_performance, get_sector_pe, get_sector_performance, get_sectors_performance: The exchange whose companies are averaged, "NASDAQ", "NYSE" or "AMEX". For get_stock_screener: The exchange code to restrict the screen to, e.g. "NASDAQ". Leave unset to use the default of the indicator you selected. Defaults are 'NASDAQ' for get_industry_pe, get_industry_performance, get_sector_pe, get_sector_performance, get_sectors_performance; None for get_earnings_calendar, get_stock_screener. | |
| industry | No | For get_industry_pe, get_industry_performance: The industry to retrieve the history for, e.g. "Biotechnology". For get_stock_screener: The industry to restrict the screen to, e.g. "Biotechnology". | |
| indicator | Yes | Name of the specific metric to calculate, one of the listed values. Required — search_metrics finds the indicator (and its tool) for a metric by name. | |
| beta_lower | No | The maximum beta of the stock. | |
| start_date | No | Start of the date range in YYYY-MM-DD format; left empty, five years before today (or the indicator's own window). | |
| beta_higher | No | The minimum beta of the stock. | |
| price_lower | No | The maximum price of the stock. | |
| price_higher | No | The minimum price of the stock. | |
| primary_only | No | Set to true to keep only the most traded listing of each company rather than every listing (e.g. ING in Amsterdam, New York, Toronto and Frankfurt). Leave unset to use the default of the indicator you selected. Defaults are False for get_stock_screener; True for get_earnings_calendar. | |
| show_columns | No | Comma-separated names to filter the output. For historical data use the key names visible in any response record (e.g. 'Close,Volume,Return'). For financial statements use the 'metric' field values from the response (e.g. 'Revenue,Net Income,EBITDA'). Call the tool once without this parameter to see all available names, then repeat with show_columns to reduce response size and token usage. | |
| volume_lower | No | The maximum volume of the stock. | |
| volume_higher | No | The minimum volume of the stock, in shares traded. | |
| dividend_lower | No | The maximum dividend of the stock. | |
| min_market_cap | No | The minimum market cap in US dollars, such as 10e9 for ten billion. Releases without a market cap are left out. | |
| dividend_higher | No | The minimum dividend of the stock, as an amount per share over the last annual period rather than as a yield. | |
| market_cap_lower | No | The maximum market capitalization of the stock in US dollars. The screener returns the largest companies first, so this bound is only sent to it when the currency of the listings is known: with an exchange, or with a country and primary_only. Otherwise it is applied to the companies returned. | |
| market_cap_higher | No | The minimum market capitalization of the stock in US dollars (not in millions), e.g. 1_000_000_000 for $1 billion. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |