iran-bourse-mcp

fund_ranking

Read-onlyIdempotent

Rank and screen Iranian investment funds by return, net assets, or type to compare performance and shortlist candidates; filter out young or market-maker funds for fair rankings.

Instructions

Ranking and screening of the investment-fund registry (صندوق‌های سرمایه‌گذاری): about 580 funds of 15 types, not only the exchange-traded ones, with net assets, units, redemption/issue/statistical NAV (ابطال، صدور، آماری), returns over 1 day to 1 year and since inception, portfolio mix (stock/bond/deposit), manager and NAV date. Sort by any return or size, filter by type and minimum net assets. Returns are percent as published, null where the fund is too young. The registry has no ticker: find the traded unit with search_symbol on the fund's name, then etf_nav for its NAV premium. Market-maker and very young funds show extreme returns, so filter them for a fair ranking.

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

Input Schema

Name	Required	Description	Default
`limit`	No	Most funds to return (default 25) (max 300)
`detail`	No	'compact' (default) or 'full' (adds custodian, guarantor, website, top-5 holdings, start date and the mostly empty investor-mix, yield and market-maker fields)	compact
`sort_by`	No	return_1y (default; also return_1d, return_1w, return_1m, return_3m, return_6m, return_since_inception, or short forms such as 1m, 3m), net_assets, units, nav or age	return_1y
`fund_type`	No	Fund type: fixed_income (درآمد ثابت), equity (سهام: every stock fund), equity_general (در سهام), mixed (مختلط), gold (طلا و کالا), market_maker (بازارگردانی), sector, leveraged, index, venture, private, project, fund_of_funds, real_estate, principal_protected, pension; a Persian name or fragment, a numeric type id, or a comma-separated list. Omit for every type.
`descending`	No
`min_net_assets`	No	Smallest net assets (خالص ارزش دارایی) in RIAL, e.g. 1e13 = 10 trillion rial = 1 trillion toman. Funds without a figure are dropped

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 description focuses on domain behavior: returns are 'percent as published, null where the fund is too young', the registry has no ticker, and market-maker/young funds distort rankings. That is genuinely useful context beyond the annotations, though pagination/limit behavior is left to the schema.

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 sentence, caveats last, and every sentence carries information. There is mild redundancy in re-listing the return horizons and portfolio-mix fields that the schema already enumerates, which keeps it from a 5.

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?

With no output schema, the description does the work of describing what comes back (NAVs, returns, portfolio mix, manager, NAV date) and flags the null-return and extreme-return edge cases. What remains thin is guidance on result size/pagination, which is delegated to the limit parameter's schema text.

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 already 83%, but the description adds real meaning: sorting by 'any return or size', filtering by type and minimum net assets, and the null-return semantics for young funds. The RIAL-unit hint for min_net_assets is in the schema, so the description doesn't need to repeat it.

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 opens with a specific verb+resource ('Ranking and screening of the investment-fund registry') and immediately scopes it ('about 580 funds of 15 types, not only the exchange-traded ones'), which cleanly separates it from etf_nav and screen_stocks. It also enumerates the returnable fields, so an agent knows exactly what domain this covers.

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?

It routes the agent explicitly to siblings: 'find the traded unit with search_symbol on the fund's name, then etf_nav for its NAV premium', and advises filtering market-maker and very young funds 'for a fair ranking'. It lacks an explicit when-not-to-use statement (e.g. use screen_stocks for equities), so it falls just short of a 5.

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