iran-bourse-mcp

index_history

Read-onlyIdempotent

Retrieve historical point values for Tehran and Fara Bourse indices, with daily closes, change percentages, drawdown, volatility, and optional intraday five-minute data for range analysis.

Instructions

History of any index (تاریخچه شاخص) in index points, not rial: the total index (شاخص کل) back to 2008, equal-weight, free-float, any industry index such as فلزات or بانک, and the Fara Bourse indices. Rows ascending with close, low, high and daily change %, plus a summary of the whole requested range: change %, highest and lowest close with dates, maximum drawdown, up/down days and a volatility estimate. Days the market was closed are flagged flat and kept out of the statistics. With intraday=true: today's 5-minute path with day high/low and the previous close.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "index": "<index>"
    },
    "name": "index_history"
  }
}

Input Schema

Name	Required	Description	Default
`index`	Yes	Index name or fragment: 'شاخص کل', 'شاخص کل (هم وزن)', 'شاخص آزاد شناور', 'فلزات', 'بانک', 'شاخص کل فرابورس' (English: total, equal_weight, fara), an industry code such as 27, or an insCode from the indices tool. A fragment that matches several indices is an error that lists them.
`limit`	No	Most rows to return (default 120). Longer ranges are thinned by granularity, or cut to the newest rows (max 500)
`to_date`	No	Range bound: Gregorian 2026-11-03 / 20261103 or Jalali 1405/08/12. Omit for no bound.
`intraday`	No	True: today's 5-minute path of the index (روند شاخص در روز) instead of daily history; dates and granularity are ignored
`from_date`	No	Range bound: Gregorian 2026-11-03 / 20261103 or Jalali 1405/08/12. Omit for no bound.
`granularity`	No	'auto' (default: daily rows if the range fits limit, else weekly, monthly, quarterly or yearly closes), 'daily', 'weekly' (Saturday-start), 'monthly', 'quarterly' or 'yearly' (Jalali)	auto

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.4.0Nov 6, 2026

TDQS

A4.3/5.0

Behavior4/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, and the description still adds real behavior: closed-market days are flagged flat and excluded from statistics, long ranges are thinned by granularity, and the whole range carries a summary (drawdown, up/down days, volatility). It does not state rate limits or whether the volatility figure is annualized, which keeps it from a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with what the tool returns, then the range summary, then the intraday mode. Dense but every clause carries information (units, index families, closed-day handling, aggregation), with 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?

There is no output schema, so the description carries the return-value burden and does so: row columns (close, low, high, daily change %), ascending order, range summary statistics, and the intraday path contents. An agent knows what it will receive and how closed days and thinning affect the result.

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%, so the schema already documents index, limit, date bounds, intraday and granularity. The description reinforces how range, granularity and limit combine to thin results and how intraday overrides dates, but adds little syntax or format detail beyond what the schema already supplies — baseline 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?

Names a specific verb+resource (index history in index points, not rial) and enumerates the index families covered: total, equal-weight, free-float, industry (فلزات, بانک) and Fara Bourse. The 'index points, not rial' clarification and the intraday variant let an agent distinguish it from price_history and indices without opening the schema.

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 for use, including the routing hint that an insCode can come from the indices tool, and the intraday=true mode for today's 5-minute path. It stops short of explicitly naming when to prefer price_history or market_snapshot instead, so no true exclusions are stated.

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