Livermore

Screen companies by market cap

screen_stocks

Read-onlyIdempotent

US-listed companies by market cap, largest first (dir=asc for smallest first), optionally within min_market_cap_usd and max_market_cap_usd (US dollars, both inclusive; give either, both or neither). For companies around $100 million, try for example min_market_cap_usd 50000000 and max_market_cap_usd 200000000. Market cap is the latest daily closing price of the company's primary ticker times the shares outstanding on its latest SEC 10-K or 10-Q cover page (shares_as_of), adjusted for stock splits since then (split_factor, 1 = none). It is recalculated every US trading day after the close; close_date is the trading day of the close used. No stock price is returned. Companies without a market cap are not listed: no_price or stale_price (no daily close in the last 7 days, for example OTC or halted stocks), no_shares or stale_shares (no cover-page share count within about 400 days, common for companies whose cover lists several share classes separately, such as GOOGL/GOOG, BRK or META), foreign_filer (a Form 20-F filer: the US listing is usually ADSs and the ADS ratio is not in SEC data), shares_mismatch (the cover-page share count does not match the listed shares: 13F institutions report holding more than 1.5 times the cover-page shares, which points to several share classes or ADSs, or the company has two or more traded common lines whose latest closes differ by more than 1.25 times, such as multi-fund ETP trusts like ProShares Trust II that share one cover-page share count) or out_of_range (an implausible value, including a market cap below $1 million). So Form 20-F issuers whose US shares are ADSs, companies whose cover page lists several share classes and multi-fund ETP trusts are missing. One row per company: ticker (the priced ticker), name, exchange, SIC industry, market_cap_usd, close_date, shares, shares_as_of, split_factor and url (the stock page). total counts every matching company and as_of is the newest close date. To research a company, follow up with get_stock, get_financials and get_insider_trades. At most 200 rows per call; use page.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`dir`	No	desc = largest market cap first (default); asc = smallest first.	desc
`page`	No	Page number starting at 1; each page has `limit` rows. Check has_more.
`limit`	No	Maximum rows to return (1-200, default 25).
`max_market_cap_usd`	No	Largest market cap in US dollars, inclusive; not below min_market_cap_usd. Default: no maximum.
`min_market_cap_usd`	No	Smallest market cap in US dollars, inclusive (100000000 = $100 million). Default: no minimum.

Output Schema

TableJSON Schema

Name	Required	Description
`note`	Yes
`page`	Yes
`as_of`	Yes	The newest close date in the market cap data; null before it is loaded.
`limit`	Yes
`total`	Yes	Number of companies matching the range (all pages).
`filters`	Yes
`has_more`	Yes
`companies`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

AddedOct 11, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description goes far beyond them: the exact market-cap formula (close x cover-page shares, split-adjusted), daily recalculation after close, the 200-row cap, and a full enumeration of why companies are silently absent (no_price, stale_price, no_shares, foreign_filer, shares_mismatch, out_of_range). The disclosure that GOOGL/BRK/META-class issuers are missing is exactly the kind of surprise an agent must know in advance.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded correctly — sort order and filters come first, methodology and exclusions after. It is long, and the row-field inventory (ticker, name, exchange, ... url) partially duplicates the output schema, but the exclusion taxonomy genuinely earns its space because it flags non-obvious missing data.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, yet the description still sketches the row shape, reports total/as_of semantics, and covers pagination limits and follow-up paths. Combined with the methodology and exclusion notes, an agent has everything needed to call and interpret this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so 3 is the baseline; the description exceeds it by giving illustrative dollar values for a realistic screen and stating that either, both, or neither bound may be supplied. It adds usable intuition about bound semantics beyond the schema's terse 'inclusive / default: no maximum' phrasing.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening clause gives a specific verb+resource+ordering: 'US-listed companies by market cap, largest first (dir=asc for smallest first)'. It is immediately distinguishable from siblings like get_stock (single company) or list_short_interest, and the optional cap-range scoping is stated up front.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It supplies a concrete usage scenario ('For companies around $100 million, try min 50000000 and max 200000000') and routes the agent onward for deeper work ('follow up with get_stock, get_financials and get_insider_trades'). What it lacks is an explicit when-not-to-use or a named same-purpose alternative, but the screening context is unambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Livermore tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?