iran-bourse-mcp

commodity_market

Read-onlyIdempotent

Query Iran Mercantile Exchange session data: view offers, contracts, traded tons, closing prices in rial per kg and value by hall or product, or get IME's summary roll-ups and dollar rate.

Instructions

Iran Mercantile Exchange physical market (بورس کالای ایران: steel, copper, aluminium, zinc, cement, petrochemicals, oil products, bitumen, agricultural goods), straight from ime.co.ir. view='trades' lists a session's offers and contracts: product, producer, hall (تالار), contract type (cash نقدی, forward سلف, credit نسیه; matching مچینگ), delivery date, offered / demand / traded tons, weighted-average closing price with low, high and base price in RIAL PER KILOGRAM, and value in RIAL, with totals by hall and contract type and the top products by value. view='summary' gives IME's roll-ups: value and traded / offered tons per ring, traded value per market (physical, futures, options, financial, certificates), one row per session and IME's dollar rate. Units are in the key names (volume_tons, price_rial_per_kg, value_rial). Without a date the latest session is used; IME trades Saturday to Wednesday, so Thursday and Friday are empty. The trades list leaves out the sub-market and is smaller than the summary: never add them. The exchange-traded boards (gold and saffron certificates, standard forwards, commodity funds, futures) are in top_lists (commodity group) and market_watch (security_type='commodity').

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

Input Schema

Name	Required	Description	Default
`date`	No	Gregorian 2026-11-03 / 20261103 or Jalali 1405/08/12. Omit for the latest trading day.
`view`	No	'trades' (default): the session's offers and contracts, one row per symbol. 'summary': IME's own roll-ups by ring and market, one row per session, and its dollar rate.	trades
`group`	No	Main group: 1 industrial صنعتی (metals, steel, copper, aluminium, cement), 2 agricultural کشاورزی, 3 petrochemical پتروشیمی, 4 mining معدنی, 5 oil products فرآورده‌های نفتی, 6 real estate; a name or fragment works too. Omit for all. Applies to view='trades'.
`limit`	No	Maximum rows to return (default 20) (max 100)
`product`	No	Fragment of the product, symbol, producer or supplier name, e.g. 'میلگرد', 'مس', 'قیر', 'فولاد مبارکه'. Applies to view='trades'.
`sort_by`	No	value (default), volume, price, demand, offered or name
`to_date`	No	Range bound: Gregorian 2026-11-03 / 20261103 or Jalali 1405/08/12. Omit for no bound.
`traded_only`	No	True (default): only rows that traded. False also lists offers that found no buyer (null prices).

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.4.0Nov 6, 2026

TDQS

A4.8/5.0

Behavior5/5

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

The annotations already declare read-only, idempotent, open-world and non-destructive behavior, but the description adds substantive operational context. It discloses the source, default-to-latest-session behavior, Saturday-to-Wednesday trading, empty Thursday/Friday sessions, row contents, units, and the fact that the trades view omits the sub-market and is smaller than the summary.

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?

The description front-loads the market and view definitions and remains information-dense rather than padded. However, the long parenthetical commodity list and dense field enumeration make it a wall of text that could be more scannable with structure.

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?

No output schema exists, so the description must carry return-value context; it does so by enumerating trades fields, explaining summary roll-ups, units, totals, and top products. For a complex eight-parameter tool, it provides enough information to call it correctly and interpret the results.

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 input schema already documents all eight parameters in detail. The description adds some useful semantics beyond the schema, notably default-to-latest behavior and trading-day effects for date, plus the distinction between trades and summary views, but it adds little for group, product, sort_by, or traded_only beyond what the schema provides.

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 data source and domain (IME physical market, ime.co.ir) and clearly separates its two modes, view='trades' and view='summary'. It also names sibling tools that cover exchange-traded commodity boards, so an agent can distinguish this physical-market tool from top_lists and market_watch.

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

Usage Guidelines5/5

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

It explicitly says what each view returns, when to omit the date, which weekdays are empty, and where related exchange-traded boards live. The phrase 'never add them' is slightly ambiguous, but the surrounding routing guidance is otherwise explicit and actionable.

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