iran-bourse-mcp

option_chain

Read-onlyIdempotent

Retrieve Tehran derivatives option chains by underlying and expiry, showing strikes with call/put prices, volume, open interest, and computed moneyness, intrinsic/time value, ratios, and max pain.

Instructions

Option chain (اختیار معامله) of the Tehran derivatives market: for an underlying ('اهرم', 'شستا', 'وبملت' ...) and expiry, every strike with its call (خرید) and put (فروش) leg - last/close price, bid/ask, volume, value, open interest, change % - plus derived (computed, not published) moneyness ITM/OTM, intrinsic and time value, break-even, bid-ask spread, put/call ratios, top open-interest strikes and an estimated max pain. Omit underlying to list the underlyings that have options. Prices are rial per underlying unit, one contract = contract_size units; legs with no trade today show no price; open interest is the clearing house's daily figure.

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": "option_chain"
  }
}

Input Schema

Name	Required	Description
`limit`	No	Chain: maximum strike rows over all expiries (default 15; the strikes nearest the underlying's price, or the top by sort_by, are kept). Underlyings list: maximum underlyings (default 30). (max 60)
`expiry`	No	'nearest' (default), 'all', or one expiry date: Gregorian 2026-11-18 or Jalali 1405/08/27.
`market`	No	'bourse' or 'fara' (Fara Bourse). Omit for both where applicable.
`sort_by`	No	Chain: strike (default), distance (from the underlying's price), volume, open_interest, value. Underlyings list: open_interest (default), volume, value, name, expiry.
`moneyness`	No	'itm' (in the money), 'otm' or 'atm' (the strike nearest the underlying's price). Applies to each leg: an ITM call at 50,000 pairs with an OTM put.
`min_volume`	No	Only legs with at least this many contracts traded today
`underlying`	No	Underlying symbol or fragment, e.g. 'اهرم', 'شستا', 'وبملت', 'شپنا' (or one of its option symbols such as 'ضهرم8029'). Omit to list the underlyings that have options, with expiries, open interest and volume.
`option_type`	No	'call' (خرید), 'put' (فروش) or omit for both
`min_open_interest`	No	Only legs with at least this many open contracts
`strike_window_pct`	No	Only strikes within this percent of the underlying's price, e.g. 10

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.4.0Nov 6, 2026

TDQS

A4.1/5.0

Behavior4/5

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

The description goes well beyond the annotations, which already state that the tool is read-only and idempotent. It discloses that derived figures (moneyness, intrinsic and time value, break-even, max pain) are computed rather than published, that prices are in rial per underlying unit, that one contract equals contract_size units, that legs with no trade today show no price, and that open interest is the clearing house's daily figure. It omits the pagination behaviour of the limit cap and shows no error cases, so the description discloses a substantial amount but has minor gaps.

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 and scope are front-loaded in the first clause, and the three sentences contain no filler. The opening sentence is very long and carries a heavy load of parenthetical detail, which makes scanning harder, but every clause still contributes specific information.

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 tool with 10 parameters and no output schema, this is close to complete: it enumerates the returned fields and the derived metrics and flags data-quality caveats. The only gaps are pagination or truncation behaviour beyond the schema's limit note and the shape of the underlyings-list response.

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 coverage is 100% and every parameter already carries a detailed description in the schema, including limit, sort_by, moneyness and strike_window_pct. The description adds domain framing (rial pricing, contract_size units) but no parameter-level meaning beyond what the schema already provides, so the baseline of 3 applies.

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 resource (the option chain of the Tehran derivatives market) along with its scope (an underlying plus an expiry, each strike's call and put leg) and the fields returned (last price, bid/ask, volume, open interest, derived moneyness, max pain and so on). An agent can distinguish it from the futures_market, commodity_market and energy_market siblings purely from this text.

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 description gives clear routing between the tool's two modes, stating 'Omit underlying to list the underlyings that have options', which tells the agent which mode to request. It never, however, compares itself with alternative tools (quote, order_book, futures_market), so the agent still has to infer when an option chain rather than a quote is the right call.

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