Yahoo Finance MCP Server

Stock screener

screen

Read-only

Filter stocks by criteria such as dividend yield, P/E ratio, market cap, region, sector, or exchange to find investment opportunities.

Instructions

Find stocks by criteria, e.g. dividend payers in a region or cheap large caps.

Fields are these aliases, or a raw Yahoo screener field name:

market: market_cap, price, change_percent, change_52w_percent, volume, avg_volume_3m, beta
valuation: pe_ratio, peg_ratio, price_to_book, price_to_sales, ev_to_ebitda
dividend: dividend_yield, forward_dividend_yield, dividend_growth_years
profitability and growth: return_on_equity, return_on_assets, net_margin, revenue, revenue_growth, eps_growth
balance sheet: debt_to_equity, current_ratio
ownership: insider_percent, institutional_percent, short_percent_of_float
esg_score
categories, eq or is-in only: region (country code, 'us', 'de'), exchange (Yahoo code, 'NMS', 'GER'), sector ('Technology'), industry (a key or name from get_sector)

Percentages are in percent, 3 means 3 %. A loss makes pe_ratio negative, so pair lt with gt 0. region is where a stock is listed, not where the company sits, so 'de' includes foreign companies traded in Germany, and a company appears once per listing. Preferred shares are listings too (on US exchanges symbols like JPM-PD), carrying the common stock's eps and market cap, so their pe_ratio means nothing. Returns total (all matches) and one row per match with price, valuation and dividend figures. A row's dividend_yield can be missing or differ markedly from the filter, which holds for Yahoo's screener data, not for that column. The other filters' figures are not in the rows: get_company_info adds beta and forward P/E, get_holders the ownership shares, get_financials the statements behind margins, growth and debt.

Input Schema

Name	Required	Description	Default
`limit`	No	Maximum number of matches to return.
`offset`	No	Matches to skip, for the next page.
`filters`	Yes	Conditions that must all hold, e.g. [{"field": "dividend_yield", "op": "gt", "value": 3}].
`sort_by`	No	A numeric field or alias to sort by.	market_cap
`sort_desc`	No	Largest first.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.8.6Oct 17, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds real behavioral nuance beyond that: results are the total match set with one row per listing, a row's dividend_yield can be missing or diverge from the filter, and preferred shares carry meaningless pe_ratio values. It does not discuss rate limits or latency, but the disclosure is rich.

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-loads purpose, then organizes aliases by category, then records caveats. The alias enumeration is long but each entry is load-bearing reference material. Slightly dense, but no filler sentences.

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?

With an output schema present the description needn't detail return values, yet it still clarifies row contents and the one caveat that matters (dividend_yield mismatch). Combined with alias coverage, op restrictions, and sibling pointers, nothing an agent needs to invoke this correctly is missing.

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

Parameters5/5

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

Although schema coverage is 100%, the schema only says field is 'an alias or a raw Yahoo screener field'. The description goes well beyond it by enumerating every valid alias grouped by category, and by documenting the op semantics (categories/region/exchange/sector/industry accept eq or is-in only), the percent convention, and the btwn value shape.

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?

States a specific verb and resource ('Find stocks by criteria') and immediately scopes it with concrete examples ('dividend payers in a region or cheap large caps'). An agent can distinguish this from the many sibling getters (get_quote, get_financials) because it is the only filter-driven discovery tool.

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?

Gives clear context via examples and explicitly routes the agent to companions for data the rows lack ('get_company_info adds beta and forward P/E, get_holders the ownership shares'). It does not, however, state when to prefer the sibling 'search' tool over screening, so the alternative-selection guidance is incomplete.

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