Skip to main content
Glama
Sign In

DocStoX

by com.docstox
OverviewDiscussionsAdmin

Screen stocks

screen_stocks
Read-onlyIdempotent

Custom stock screener with fundamental, technical, market, ownership and corporate-action filters.

Examples:

  • Value stocks: max_pe=15, max_pb=3, min_roe=15, max_debt_equity=0.5

  • Clean ownership: max_promoter_pledged_pct=5, min_promoter_pct=50

  • Momentum: supertrend_bullish=True, min_rsi=50, max_rsi=70

  • Quality: min_piotroski=7, min_roce=20

  • Sector filter: sector='Information Technology', min_roe=20

  • Clean + growing + catalyst: min_roce=15, max_debt_equity=0.5, min_revenue_yoy_pct=15, has_upcoming_corporate_action=True

sort_by options: market_cap, ltp, pe_ratio, roe, roce, roa, rsi_14, revenue_yoy_pct, pat_yoy_pct market_cap_cat: 'Large Cap', 'Mid Cap', 'Small Cap' (also accepts 'Large'/'Mid'/'Small'/'Micro')

NOTE on "catalysts": has_upcoming_corporate_action only detects structured corporate actions (dividend/bonus/split/rights/buyback ex-dates) — NOT real-world catalysts like order wins, contract awards, regulatory approvals, or capacity expansion, and order book size/growth is not a DB column at all. This tool narrows candidates; real catalysts and moat evidence live in news, company documents and filings. Stocks listed in the last 3 months are excluded by default (thin price/fundamentals history breaks technical + quality screens) — pass min_listing_age_months=0 to disable.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "screen_stocks"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMax rows to return (1-100).
max_pbNoMaximum price-to-book ratio, e.g. 3.
max_peNoMaximum trailing P/E ratio, e.g. 20.
min_pbNoMinimum price-to-book ratio, e.g. 0.5.
min_peNoMinimum trailing P/E ratio (price / EPS), e.g. 5.
sectorNoSector name, e.g. 'Information Technology'. Case-insensitive.
max_rsiNoMaximum 14-day RSI (0-100), e.g. 70.
min_roaNoMinimum return on assets, percent (5 = 5%).
min_roeNoMinimum return on equity, percent (15 = 15%).
min_rsiNoMinimum 14-day RSI (0-100), e.g. 50.
sort_byNoColumn to rank by.market_cap
min_roceNoMinimum return on capital employed, percent (20 = 20%).
min_roicNoMinimum return on invested capital, percent.
sort_dirNoDESC = largest first, ASC = smallest first.DESC
above_sma200Notrue = price above its 200-day simple moving average.
golden_crossNotrue = 50-day SMA crossed above the 200-day SMA in the latest session.
max_altman_zNoMaximum Altman Z (distress screening).
min_altman_zNoMinimum Altman Z-score; above ~3 is the 'safe' zone, below 1.8 distress.
near_52w_lowNoWithin 5% of the 52-week low.
new_52w_highNoPrinted a new 52-week high.
min_piotroskiNoMinimum Piotroski F-score (0-9); 7+ is strong.
market_cap_catNoSize band. A trailing ' Cap' is stripped before the query, so either spelling works.
min_net_marginNoMinimum net profit margin, percent.
max_debt_equityNoMaximum debt-to-equity ratio as a multiple (0.5 = debt is half of equity).
min_pat_yoy_pctNoMinimum net-profit (PAT) growth year on year, percent.
volume_breakoutNoVolume broke out versus its own average.
min_delivery_pctNoMinimum delivery percentage of traded volume (0-100), e.g. 50.
min_promoter_pctNoMinimum promoter holding %. Also sparse here; screen_advanced own_promoter_pct reads the source table.
min_ebitda_marginNoMinimum EBITDA margin, percent.
min_free_cash_flowNoMinimum latest annual free cash flow in Rs crore; 0 keeps only FCF-positive companies.
supertrend_bullishNotrue = Supertrend indicator in an uptrend; false = downtrend.
max_net_debt_ebitdaNoMaximum net debt / EBITDA as a multiple, e.g. 2.
min_revenue_yoy_pctNoMinimum revenue growth vs the same period a year earlier, percent (15 = 15%).
catalyst_window_daysNoDays ahead to look for an ex-date when has_upcoming_corporate_action=True.
max_promoter_pledgedNoBROKEN: reads mv_screener_snapshot.promoter_pledged_pct, which is ~0% populated in this DB, so any value here matches almost nothing. Use screen_advanced with the own_pledged_pct metric instead, which reads the source table.
min_interest_coverageNoMinimum interest coverage (EBIT / interest) as a multiple, e.g. 3.
min_listing_age_monthsNoMinimum months since listing. Defaults to 3 (thin history breaks technical screens); pass 0 to include new listings.
has_upcoming_corporate_actionNotrue = an ex-date (dividend, bonus, split, rights, buyback) falls within catalyst_window_days.

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.2/5.0
Behavior5/5

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

Annotation already covers readOnly/idempotent, and the description still adds non-obvious behavior: new listings are excluded by default (min_listing_age_months=0 to disable) and has_upcoming_corporate_action only detects structured ex-dates, explicitly not real-world catalysts. These are exactly the surprises an agent would otherwise hit at runtime.

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?

Purpose is front-loaded, then grouped examples, then sort/market-cap options, then two caveat notes — a logical order that makes the length (justified by 38 parameters) easy to scan. The sort_by enumeration duplicates part of the input schema while being incomplete, which is the one wasteful/misleading element.

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

Completeness4/5

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

For a 38-parameter screener with full schema coverage and an output schema, all that is needed beyond structured fields is default behavior and caveats, both of which are supplied (listing-age default, catalyst scope). It omits any screener-sibling routing and limit/pagination commentary, so it is strong but not exhaustive.

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 the baseline is 3. The description adds real value with concrete filter combinations showing how parameters are meant to be used together, plus the market_cap_cat relaxed-spelling note. Its sort_by list is only a partial subset of the 20-value enum, which is slightly misleading, so it stops short of 5.

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

Purpose4/5

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

Opens with a specific resource and scope: 'Custom stock screener with fundamental, technical, market, ownership and corporate-action filters.' An agent immediately knows this is a multi-filter candidate-narrowing screener. It never names or contrasts itself with the sibling screeners (screen_advanced, screen_stocks_technical, screen_patterns), so it falls short of the sibling-differentiating bar for a 5.

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?

The six named recipes (value, clean ownership, momentum, quality, sector, clean+growing+catalyst) tell an agent concretely when this tool applies, and the catalyst NOTE routes non-structured catalyst work to news/documents/filings. However it gives no explicit screener-vs-screener selection rule against screen_advanced, so the guidance is clear but not complete.

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

All DocStoX toolsInspect
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