iran-bourse-mcp

index_constituents

Read-onlyIdempotent

Retrieves an index’s member stocks with close, change %, volume, value, and index-point impact, plus totals and sortable fields for market analysis.

Instructions

Member stocks of an index (سهام شاخص) with close, change %, volume, value and each stock's effect in index points on the total index (تاثیر در شاخص, from the exchange), plus totals: members, advancers/decliners, traded value, sum of effects. The exchange publishes no index weights, so market-cap share is only a derived proxy (sort_by market_cap). Effects are for the latest session and are left out, with a note, when the exchange's table does not add up to the index move; for a sector index they are the effect on the total index, not on the sector index.

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_constituents"
  }
}

Input Schema

Name	Required	Description	Default
`index`	Yes	Index name, fragment, industry code or insCode, as for index_history ('شاخص کل', 'فلزات', 'بانک', 'شاخص آزاد شناور', 'شاخص کل فرابورس')
`limit`	No	Most members to return (default 25) (max 500)
`sort_by`	No	effect (points added to the total index, the default), abs_effect, value (traded value), volume, trades, change (closing price change %) or market_cap	effect
`descending`	No

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.4.0Nov 6, 2026

TDQS

A4.1/5.0

Behavior5/5

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses genuinely non-obvious behavior: the exchange publishes no index weights so market-cap share is only a derived proxy, effects are for the latest session only, effects are omitted (with a note) when the exchange table does not reconcile to the index move, and for sector indices the effects refer to the total index rather than the sector itself. These are exactly the traps an agent would otherwise fall into.

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?

Two sentences, front-loaded with what the tool returns, with caveats packed into trailing clauses so the core facts come first. It is dense but nearly every phrase carries information; the parenthetical Persian terms and repeated caveats make it slightly harder to skim than it needs to be.

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?

With no output schema, the description must carry the return-shape burden and it does: it lists per-row fields, the aggregate totals (members, advancers/decliners, traded value, sum of effects), and the conditions under which a field is absent. Nothing essential to calling or interpreting the result is missing for a four-parameter read tool.

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?

At 75% schema coverage the schema already documents index, limit and the sort_by option list, so the description's job is to add interpretation. It does so by explaining that market_cap is a derived proxy rather than a published weight and by clarifying that effect means 'points added to the total index', which disambiguates the default sort ordering in a way the schema does not.

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?

It states a specific resource (member stocks of an index) and enumerates exactly what each row carries: close, change %, volume, value, effect in index points, plus aggregate totals. The scope is clear enough that an agent can tell it is a constituent-listing tool, but it never names or contrasts the sibling index_contributors, which appears to overlap with the per-stock effect data.

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

Usage Guidelines3/5

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

Usage is only implied: the mention of 'sort_by market_cap' tells the agent to use the market_cap sort when it wants a weight-like ranking, but there is no explicit 'use this when...' statement, no exclusion telling the agent to prefer index_contributors for contributor questions, and no stated prerequisites for the index argument beyond a pointer to index_history.

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