iran-bourse-mcp

screen_stocks

Read-onlyIdempotent

Screen stocks by a validated expression using live quotes, historical windows, and money flow, returning only symbols that meet your condition in one call.

Instructions

Stock screener (فیلتر نویسی): the filter box of tsetmc.com driven by an expression. Returns only the stocks that pass your condition right now, using today's live values plus up to 60 past trading days (close[1], avg(volume, 20), count(close_pct > 0, 3)) and real/legal money flow, in one call with a validated, safe expression (nothing is executed).

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

Name	Required	Description	Default
`sort`	No	Expression to sort by, e.g. 'volume / avg(volume, 20)'. Default: the preset's, else value.
`limit`	No	Maximum rows to return (1-300); the server rejects larger values
`filter`	No	Condition checked for every stock, e.g. "volume > 2 * avg(volume, 20) and close_pct > 1". Today: last close open high low yesterday last_pct close_pct volume value(rial) trades pe eps market_cap bid_volume ask_volume at_upper_limit buy_queue real_net_value real_buyer_power industry symbol. Past days: close[1] (yesterday), avg(volume, 20), highest(high, 10), count(close_pct > 0, 5), all(close_pct < 0, 3). Operators: and or not, has(industry, 'بانک'), 5B = 5 billion rial. All fields and functions: screener_reference.
`market`	No	'bourse' or 'fara' (Fara Bourse). Omit for both where applicable.
`preset`	No	Ready-made filter, e.g. volume_surge, smart_money, breakout_20d, buy_queue (screener_reference lists them). ANDed with filter.
`columns`	No	Expressions to show, optionally 'expr as label'. Default: symbol, last, close_pct, volume, value plus the fields and window values the filter uses.
`adjusted`	No	Adjust past prices for capital increases and dividends so close[5] is comparable with close
`industry`	No	Industry name substring, e.g. 'بانک'
`descending`	No
`security_type`	No	Instrument type: 'stock' (default, سهام), 'fund' (صندوق, has nav and nav_premium_pct), 'option', 'future', 'bond', 'rights', 'commodity', 'base' or 'all'	سهام
`include_untraded`	No	Also consider symbols with no trades today

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.4.0Nov 6, 2026

TDQS

A3.9/5.0

Behavior3/5

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

Annotations already declare readOnly, idempotent, non-destructive, so the bar is lower; the description still adds real value by disclosing data freshness (today's live values plus up to 60 past trading days) and that the expression is validated and never executed, which reassures on injection safety. It says nothing about result size behavior, latency, or failure modes on invalid expressions, so it stays a solid 3 rather than a 4.

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?

Short and front-loaded with the core identity before the data-source and safety notes. The parenthetical example list is dense but earns its place by demonstrating the expression language in one line; only the trailing safety clause feels mildly tacked on.

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 an 11-parameter tool with no output schema and strong annotation coverage, the description supplies what matters: what data window is used, what the expression language can touch, and where to find the full vocabulary. Default column behavior is left to the schema, which handles it adequately.

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

Parameters3/5

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

Schema description coverage is 91%, so the schema already explains filter, sort, preset, columns, market, and limits in detail. The description mostly restates expression capability with the same examples (avg(volume, 20), close[1]); it does add that preset is ANDed with filter, but that is already in the preset field's own description.

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 description names a specific verb and resource (stock screener / the tsetmc.com filter box) and states precisely what it returns: only symbols passing an expression, using live values plus up to 60 days of history. Referencing screener_reference for the full field list cleanly separates this tool from its reference sibling.

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?

Usage is clear from the framing (screen stocks against a condition now) and the description routes agents to screener_reference for fields and presets. It stops short of explicit when-not-to-use guidance or naming an overlapping alternative such as market_watch or top_movers for unfiltered listing.

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