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

Annotations already declare readOnly, idempotent, non-destructive, and open-world behavior, so the safety profile needs no restating. The description adds genuinely new context: it is a Mofid-side proxy for Codal rather than a direct Codal reader, and it specifies the shape of each returned row (title, publish time, company, period, links to Codal page, PDF, attachments). The default window is disclosed via the schema rather than the prose.

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

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

Three short lines, front-loaded with what is searched, then the source/routing caveat, then the return shape. No sentence is redundant with the name or with structured fields.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly spends its final line on what a row contains, which is what a caller most needs to interpret results. It is a zero-required-parameter, read-only search tool whose pagination and date defaults live in the schema, so little else is owed. Slightly incomplete on whether results are Persian-only or how attachments are fetched.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter (limit, offset, symbol, to_date, from_date, report_type) is already documented in the schema. The description only restates the filter axes as 'company, report type and date' without adding format, defaults, or example values beyond what the schema supplies. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource ('Search Codal filings') and enumerates the document classes covered (financial statements, board notices, AGM invitations, monthly activity), plus the three filter axes. It separates itself from br_search and from codal-mcp, but does not state how it differs from filing-adjacent siblings such as br_news or br_stock_events.

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

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

'Use br_search if unsure of the symbol' is an explicit routing rule that prevents a wasted call. 'Source: Mofid only ... codal-mcp reads Codal directly' clarifies the data provenance decision. There is no explicit when-not guidance (e.g., use br_news for press coverage rather than filings).

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

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; the description still adds real value with the Mofid-only sourcing limit and the note that very short bills produce absurd yields (explaining the min_days default). It doesn't describe result shape or row ordering beyond the schema, keeping it below 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.

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

Three tightly packed sentences, front-loaded with the resource and followed by the routing rule and unit conventions; no filler or restatement of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a six-parameter read-only listing tool with no output schema, the definition covers sourcing, units, and a key statistical caveat. Only the returned row structure and pagination behavior are left implicit, a minor gap given limit is documented.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description goes further by defining units the schema omits: prices are Rial per 1,000,000 par, ytm is percent per year, and coupon_rate is a fraction (0.18 = 18%). That meaningfully disambiguates interpretation of sort and filter results beyond the schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('List exchange-traded bonds, sukuk and treasury bills') and previews the returned fields (maturity, coupon, price, yield to maturity), which immediately distinguishes it from the generic search sibling.

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

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

It states the alternative and why it doesn't apply: 'Bonds are not in br_search; list them here by group, symbol or yield.' It also names the data source constraint (Mofid only), so an agent knows precisely when this tool 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.

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

Annotations already declare read-only, idempotent, non-destructive, open-world behavior, so safety is covered. The description adds genuinely non-obvious behavior: the two sources return different column sets, Agah lacks several fund families, and all monetary values are in Rial. It stops short of describing what source='all' returns structurally (merged list vs. two blocks) or pagination semantics.

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

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

Front-loaded with the core purpose, then examples, then source payloads, then next-step routing — a logical funnel. The dense comma-separated field lists are justified given there is no output schema, though they read more like a spec dump than prose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the return-shape burden and does so by enumerating columns per source and stating the currency. Remaining gaps are the combined behavior of source='all' and whether limit truncates across sources — minor but relevant for a dual-source listing tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema already explains sort enums, source counts, and type families in detail. The description's only real parameter-level addition is the Rial currency unit; the per-source row lists describe return values rather than parameter meaning, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("List exchange-traded funds") plus the distinctive fields it returns (price, NAV, gap/bubble, traded value, returns). The per-source row breakdown and the closing routing line separate it from br_screener, br_fund and br_stock without requiring the agent to open any schema.

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

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

Gives concrete task examples ("cheapest gold ETF", "fixed-income ETF with the lowest bubble") and explicit alternatives with the condition that selects them: br_stock/br_fund for a single fund, br_screener for arbitrary column filtering. The agent can route correctly from this text alone.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. Beyond that the description discloses genuinely useful behavior the annotations do not: data comes from Agah only, monetary values are in Rial and returns in percent, history is ordered oldest first, and the price/returns series have unlabeled columns. It stops short of mentioning rate limits or error behavior, which keeps it at a 4 rather than 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.

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

The structure is strongly front-loaded: capability first, source/routing second, then a compact enumeration keyed to one fund, one fund plus metric, and several funds. It is dense but each clause carries distinct information; the only slight redundancy is restating the metric/history mode that the schema also describes.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

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 burden of describing return shapes, and it does so at three levels of granularity (detail fields, daily series, comparison table). Combined with units, ordering, and the 6-fund comparison cap implied by the schema, an agent has enough to call this correctly, though a hint on series length defaults would make it complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents each parameter and the baseline is 3. The description still adds meaning not in the schema: units (Rial, percent), the oldest-first ordering of metric series, and the ETF-specific extras (live bubble and order book) that a caller would not infer from parameter names alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific verb (show) and resource (an Agah investment fund) and enumerates the three output modes: detail, daily history, and side-by-side comparison. The second sentence explicitly separates it from siblings, noting that Mofid funds live in br_mofid_funds and Mofid ETFs in br_stock/br_etfs, so an agent can route correctly without opening any schema.

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

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

Usage is spelled out per cardinality of the `funds` argument: one fund yields detail (issue/redeem prices, returns vs index, dollar and gold), one fund plus `metric` yields a history series, and several funds yield a comparison. It also names the companion tools for the surrounding steps (br_search with kind='fund' to find codes, br_screener to filter many funds), which is exactly the when/when-not guidance an agent needs.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description earns credit for what it adds: result ordering (oldest first), Tehran timezone, Rial currency, the absence of OHLC in Agah rows, and data-availability caveats for minute candles. Some of these caveats are duplicated from the schema parameter descriptions rather than being new information.

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

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

Front-loaded purpose statement followed by a tight comparison of the two shapes; nearly every sentence carries information. Minor deduction for a mid-sentence line break artifact and dense phrasing that makes the shape comparison read as a block.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly takes on the burden of explaining what is returned for each source, including field lists, ordering, timezone and currency. It stops short of covering pagination interaction between days and limit or behavior when a symbol is not found.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the enum values, defaults and limits are already fully documented. The description adds conceptual meaning about how source determines the returned shape, but gives no extra syntax or constraint detail for parameters like days/limit interaction. Baseline 3 applies when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Return price history of a stock') and immediately enumerates the two data shapes it can produce. It also distinguishes itself from br_index by name, so an agent can separate it from a sibling 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.

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

Explicitly routes index queries to br_index and explains when each source mode applies (Mofid for OHLC, Agah for flow data). It does not address the boundary against other siblings like br_technical or br_quotes, so the guidance is clear but not exhaustive.

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

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

Annotations already declare read-only, idempotent, open-world, non-destructive behavior. The description adds useful source-specific behavior: Mofid versus Agah responses change based on `days`, and Agah history is limited to the total-index series.

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

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

The description is front-loaded and appropriately sized for a multi-source index tool. It is mostly efficient, with a slightly dense middle sentence explaining source behavior and Agah series limitations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only tool with no output schema, the description is complete enough: it lists the index-card data, explains daily history behavior, describes source-dependent responses, and routes the agent to correct sibling tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds meaningful interaction semantics beyond the schema by explaining that `days` changes which source answers and what history is returned.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Show a market index' and 'its daily history.' It also names how it differs from siblings, explicitly routing sector indices to br_industries and today's snapshot to br_market.

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

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

It gives clear conditional usage: without `days` only Mofid answers with the index card, while with `days` Mofid adds daily candles and Agah returns its total-index series. It also names alternatives for sector indices and today's snapshot.

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

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

Annotations already cover readOnly/idempotent/non-destructive, so the description's added value is in disclosure: money is in Rial, Agah's `industry` mode returns a return table plus member stocks, and sources answer in separate blocks with per-source error isolation. This is genuine behavioral context beyond the annotations, though pagination/return shape is not described.

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

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

Front-loaded with the verb and ranking dimensions, then source capabilities, then next steps. The telegraphic style ('Money is Rial') is efficient but slightly clipped; nearly every clause carries information, with only mild redundancy against the schema's sort/source enums.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a five-parameter, dual-source tool with no output schema, the description covers units, per-source block/error behavior, the industry drill-down mode, and follow-up tools. It stops short of describing the shape of the ranked rows or how limit applies across two blocks, which the schema only partially covers.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents sort/source/limit/industry semantics, including which sorts work per source. The description reinforces the source capability matrix and the Rial unit, but adds little syntax or format detail beyond what is structured. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (rank) plus the resource (bourse industries) and enumerates the ranking dimensions and the two data sources (Mofid, Agah). An agent can immediately distinguish this from br_stocks, br_screener, or br_market_top without opening any schema.

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

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

Explains the source split (Mofid's 53 industries with valuation ratios vs. Agah's flow/return data) and gives explicit handoff guidance: 'Next: br_technical with an industry ISIN, or br_stock.' It does not state when to prefer br_screener or br_stocks instead, so no true exclusion guidance, but the routing context is clear.

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

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

Beyond the readOnly/idempotent/openWorld annotations, it discloses a material constraint: Agah Pedia and Academy only answer from an Iranian network. It also explains partial-failure semantics with source='all' (failing source returns {'error': ...}, the other still answers), truncation via max_chars, and that article text is third-party content.

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

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

Front-loaded with purpose and workflow, then mode-specific detail, with no filler sentences. It is dense — several facts packed per sentence — but every clause carries operational information. Slightly tighter grouping by parameter would improve scannability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter, no-required-parameter, no-output-schema tool, it covers the search/read workflow, per-mode outputs (courses give 'titles and links only'), source fallback, and the geo constraint. What is missing is return shape for article search results (fields to expect before using `ref`) and pagination limits, though the schema documents the latter.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: `ref` type encodes the source (Mofid ids are numbers, Agah ids are slugs, so ref selects the source implicitly), and kind='categories' vs. kind='courses' are described by what they enumerate rather than just by enum name. Minor gap: no added guidance on `page`/`per_page` interaction.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource set ('Search the Mofid learning blog and Agah Pedia ... or read one article') and names the content domain (bourse, fund, option, gold explainers). The two modes — search vs. read one article — are stated explicitly, so an agent can tell this apart from the market-data siblings in the list.

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

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

Gives concrete triggering examples ('what is ROE', 'how do gold ETFs work') and prescribes the call sequence: search first, then re-invoke with `ref` from a result. It also routes between the three `kind` modes, saying what each returns, which is exactly the when-to-use guidance an agent needs.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description does add real behavioral context beyond them: the partial-failure contract ('with all, a source that fails shows {"error": ...} and the other still answers') and the unit ('Money is Rial'). It stops short of freshness/timing or rate-limit details, so this is solid but not rich.

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

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

Purpose is front-loaded, the routing sentence is placed last where it helps selection, and the per-source breakdown is scannable. The middle enumeration is dense but each clause maps to something an agent would otherwise have to guess; only minor trimming is possible.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates well by describing what each source returns and how failures surface. Minor gaps remain around data freshness (only 'today') and response shape, but for a read-only snapshot tool the agent has enough to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all four parameters are already documented in the schema, including the same breadth contents and prices default restated here. The description adds little parameter-level meaning beyond noting Rial units and that each source answers in its own block. Baseline 3 applies when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb and resource ('Show today's market snapshot') and then enumerates exactly what the snapshot contains per source (Mofid indices/value/volume/queues, Agah total index/money flow/movers/prices). It also names the adjacent tools and what each covers, so an agent can separate this from br_market_top, br_industries and br_rates without opening a schema.

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

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

Gives an explicit entry-point rule ('Start here for "how is the bourse today"') and then routes elsewhere: br_market_top or br_stocks for rankings, br_industries for sectors, br_rates for price history. Both the when-to-use and the when-to-use-something-else conditions are stated.

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

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

Annotations already cover read-only, idempotent, non-destructive, open-world, so the description's job is to add what they don't: it discloses the data source constraint ('Source: Mofid only'), that lists are live, the unit ('Prices are Rial'), and the shape of each row. It does not mention board-specific ordering caveats or what happens when a board has fewer than N symbols.

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

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

Three short sentences: capability first, source and sibling disambiguation second, return shape last. Each sentence carries information the agent needs and there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates by listing the returned fields (symbol, ISIN, price, daily change, ranking value) plus the price unit. It covers everything needed to call the tool, though the ordering guarantee per board and the maximum of 20 rows are only visible in the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the board enum description already groups every value by category, so the description's category examples largely restate it. The one addition is framing the call as 'top-N', which clarifies that limit is a ranked truncation rather than an arbitrary row count.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Return one of the market's live top-N lists') and enumerates example rankings, so the agent knows exactly what class of data comes back. It also names the sibling it is NOT ('Agah's own ranking ... is br_stocks'), which removes ambiguity with the most similar tool.

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

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

Explicitly routes the agent: use br_stocks for Agah-wide rankings across all stocks, use this for Mofid's live top-N boards, and use br_stock to open a single row. Both the alternative tool and the follow-up tool are named with the condition that selects them.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so safety is covered. The description's real contribution is the repeated warning that no NAV or price is included — useful behavioural context about missing data. It says nothing about freshness, caching, or whether the 19-fund set is fixed or can change.

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

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

The 'no NAV or price' point is asserted three times in three consecutive sentences, and the 'Source: Mofid only' line partially duplicates the opening sentence. The front-loaded first sentence is strong, but roughly half the text is repetition that crowds out genuinely new information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter list tool with no output schema, the description covers scope, returned fields, and the boundary against price-oriented siblings — enough to call it correctly. What is missing is only marginal: whether records are static reference data or periodically refreshed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline applies. It does implicitly confirm the call is unfiltered (no selector for fund type or risk), which saves an agent from hunting for a filter argument.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List the 19 investment funds managed under the Mofid brand'), names representative funds, and enumerates the attributes returned (type, risk level, dividend policy, asset mix). It also distinguishes itself from br_etfs, br_stock and br_fund, so an agent can route between them without opening schemas.

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

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

Gives explicit when-to-use and when-not-to-use: use this for the Mofid marketing catalogue, but use br_etfs or br_stock for prices and NAV and br_fund for Agah funds. The only mild gap is that it names 'br_stock' while a sibling is 'br_stocks', which could cause a routing slip.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, so the description only needs to add context — and it does: the Mofid-only source, the Jalali date convention, and the fact that results are the newest N taken from the site. It does not mention rate limits, failure modes, or freshness lag, which would be the remaining useful disclosures for a feed tool.

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

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

Front-loaded with the core purpose, then source constraint, then routing — good ordering. The closing sentence repeats the br_announcements routing already stated in line two, which is wasted space in an otherwise tight definition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description should hint at what comes back; it implies a list of recent items with text truncated per the chars parameter and confirms the source and date convention. Adequate for a simple read-only feed tool, though it never states the return shape (headline/link/date fields) explicitly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with enum values and defaults all documented in the schema itself, so the schema carries the parameter burden. The description adds no parameter-level detail beyond the Jalali date note (which applies to returned values, not inputs). Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Return the newest market news items') and enumerates exactly the four content types covered: exchange notices, Codal letters, Telegram posts, Mofid research. An agent can distinguish this from br_announcements without opening either schema.

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

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

Explicitly names the alternative ('Use br_announcements for a company's filing history') and a source constraint ('Source: Mofid only'). The one gap is the overlap created by kind='filings', which returns latest Codal letters here while br_announcements covers filing history — the boundary is only loosely drawn, and the alternative is repeated twice rather than used to sharpen that distinction.

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

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

Annotations already declare read-only, idempotent, non-destructive, open-world access, but the description adds substantive context the annotations cannot: the data source is Agah only, prices are quoted in Rial per underlying share, each row carries its contract size, and the single-contract mode returns margin, break-even distance, order book and real/legal flows. That is real disclosure of units and return content for a tool with no output schema.

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

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

The chain-versus-single-contract split is front-loaded in the first sentence and the closing sentence handles the prerequisite lookup. The block is a little dense with embedded quoted examples and an awkward source line, but no sentence is genuinely wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For six optional parameters and no output schema, the description covers both operating modes, the fields returned in each, currency/units, and the data-source restriction. Pagination and ordering behavior around `limit`/`sort` remain unstated, which is the main residual gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 83%, so the baseline is 3; the description goes past that by explaining the mode switch ("Pass `option` (an ISIN from the chain) for one contract") and by tying `underlying` to a search-first workflow. It still leaves the `sort` enum values and the `limit` cap unexplained, so it is good but not complete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific resource (stock-option contracts, ~1,600) and a specific dual behavior: list the chain, or show one contract when `option` is supplied. It also states what each row carries (strike, expiry, moneyness, open interest, flows), so an agent can distinguish this from siblings like br_stocks or br_screener without opening a schema.

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

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

It gives concrete use cases ("options on Shepna expiring soon", "most traded calls") and an explicit routing rule: find the underlying with br_search first if the symbol is unknown. It does not, however, exclude or compare against the other market-data siblings, so the when-not-to-use side is only implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorld, so the safety profile is covered. The description then adds genuinely non-structured context: the data source is Mofid only, prices are denominated in Rial, and 'last' means last trade while 'close' is the weighted closing price the exchange uses for change. The main remaining gap is that it doesn't say whether symbols with no data are omitted or returned as null.

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

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

Well front-loaded: the payload and batch size lead, then source, then routing advice, then field semantics. Minor redundancy remains, since 'Index and fund ids work too' repeats the earlier 'for fund and index ids' clause and could be merged.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

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 it does so by enumerating the returned fields and the currency. For a single-parameter read tool this is close to complete; the only unaddressed behaviour is handling of invalid or data-less symbols within a batch.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the schema already documents the array, its 1-30 bounds and ISIN-style ids with equity and index examples, so the baseline is 3. The description adds some meaning by confirming fund and index ids are accepted and that results are priced in Rial, but it doesn't clarify id formatting edge cases or how mixed equity/index batches are ordered.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('return live price rows') plus the exact payload fields (last, close, change, volume, limits, bid/ask, returns) and the batch range of 1 to 30 symbols. It also distinguishes itself from siblings by naming br_search (for ids) and br_stock (single symbol in depth). An agent can tell br_quotes apart from br_stock without opening either schema.

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

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

Gives an explicit usage sequence ('use it after br_search to price several symbols at once') and an explicit alternative with its selection condition ('br_stock gives one symbol in depth'). It also states a source constraint ('Source: Mofid only') and calls out that fund and index ids are valid inputs, which are the main cases where an agent might wrongly reach for a different tool.

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

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

Annotations already declare this a safe, idempotent read, and the description builds on that with real operational context: single source ('Mofid only'), unit conventions ('Rial prices: divide by 10 for Toman'), the fields each row carries in live vs history mode, ordering ('oldest first'), and coverage horizon ('back to 2019-2021'). This is information an agent cannot recover from the annotations or schema.

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

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

Front-loaded with the resource list and the live/history split, then a compact source-and-shape paragraph. Dense but every sentence carries signal; the trailing sibling reference sits awkwardly at the end of a paragraph about row formats rather than in its own routing sentence.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and four optional parameters, the description does the heavy lifting: it names the row fields, ordering, unit system and data source. What is missing is failure behavior, e.g. what happens when no code matches or when history is requested for a range beyond the available window.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline would be 3; the description earns more by explaining that history mode requires an exact code and by clarifying the unit basis behind currency/gold_coin versus commodity values. It does not add much beyond the schema's own per-parameter descriptions, so it stops short of 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource set ('Return free-market prices of currencies, crypto, coins, 18k gold, the global ounce, oil and metals') and adds the distinct history mode ('or one code's daily history'). The two modes are cleanly separated, so an agent can tell this apart from quote/screener siblings 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.

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

Explicitly names the alternative for a quick glance ('Agah's br_market also shows dollar, coin, gold and oil prices'), which steers agents away from this tool when they only need a top-level view. It also implies the history branch requires an exact code, though it never states a hard when-not condition such as 'do not use for equities or funds'.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds substantive context the annotations cannot: the data source is Mofid only, and the response shape (score scale out of 10, rating vocabulary Buy/Neutral/Sell). It does not mention volume or rate limits, but nothing here suggests those matter for a scored lookup.

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

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

Front-loaded with what is returned, then source/routing, then the three input modes – a sensible order with no filler. The "profitability, liquidity, momentum etc." list is slightly redundant with the enum, but it is a minor cost.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and five optional parameters, the description carries the return-shape burden and does it: it names the comparison fields, the rating scale and the 10-point fundamental score. Only row ordering and how the theoretical-price delta is signed are left implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema descriptions already explain the isins/section/neither exclusivity and the "overall table only" filters. The description largely restates this synthesis and only adds example section names, so it does not add meaning beyond the structured fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

"Return Bourse View's valuation scores" names a specific resource, and the sentence then enumerates the actual payload (theoretical vs market price, technical rating, fundamental score out of 10). It also distinguishes itself from br_stock and br_technical by naming what those siblings return instead.

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

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

Explicit mode selection: ISINs for named symbols, `section` to rank the market, nothing for the overall fundamental table. It also routes the agent to alternatives ("Pair with br_stock for price and ratios; br_technical (Agah) gives an indicator tally"), which is exactly the sibling disambiguation an agent needs.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description instead spends its words on provenance (Agah only), data units (returns in percent, money in Rial, fund Nav in Rial), and the ETF column-naming trap where names ending in 2 are NAV returns and the rest are market-price returns. That is genuinely non-obvious behavioral context. It stops short of describing the row/response shape or any size or performance limits for a ~1,700-instrument screener, which keeps it off 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.

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

Front-loaded with the verb, scope, and sibling routing in the first two sentences, then examples, then a dense units paragraph. Every sentence carries information, though the trailing units/column-family paragraph is compressed to the point of being easy to skim past, and the parenthetical dataset sizes sit awkwardly mid-sentence.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter, no-output-schema screener, the description covers the essentials an agent needs to call it correctly: which kind values exist, that columns must be looked up with list_columns, filter direction via max/min examples, and the unit conventions that determine whether a numeric threshold is sane. The remaining gap is that the return shape (rows of dicts keyed by column name) is never stated and there is no output schema to fill it in.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 80%, so the baseline is 3; the description earns the bump by explaining that column names are the site's own and must be discovered via list_columns, and by clarifying units per column family (percent vs Rial) and the existence of FundType for funds. It still doesn't explain the interaction between sort/ascending/limit or what a default column set contains, which the schema also leaves vague.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence gives a specific verb set (filter, sort, compare) plus the resource (stocks or funds) and scopes it to the Agah screener universe with concrete sizes (~900 stocks, 330 ETFs, 475 funds). It explicitly contrasts itself with siblings: br_etfs for a plain ETF list with NAV gap and br_fund for a single fund.

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

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

Usage is stated as concrete example queries ("stocks with P/E under 6 and ROE over 30", "best 1-year fixed-income funds", "ETFs with the lowest bubble"), and the alternatives are named with the condition that selects them (br_etfs for a plain list, br_fund for a single fund). Nothing about when to reach for this tool is left to inference.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds real context beyond them: results are per-source blocks, and one failing source does not sink the other. It does not describe result ordering or what a zero-hit response looks like, keeping it short of 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.

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

Two tight paragraphs, front-loaded with purpose then workflow, with no filler sentences. Minor duplication with the schema's `source` description about partial failure keeps it from a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, and the description compensates by explaining exactly what identifiers come back and how to consume them downstream. For a four-parameter lookup tool with full annotation coverage, nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% (kind, limit, query, source are all documented, including the caution about options), so the baseline is 3. The description still adds value by explaining what the returned identifier means per source (isin for Mofid, id/ISIN or national code for Agah) and why the two lists are kept apart, which is the semantic key to using the results correctly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb and resource set: 'Find the id of a stock, fund, option or index by name or symbol, in Mofid and Agah.' It also names the sibling tools it feeds (br_stock, br_history, br_fund, br_options), so an agent can place it precisely in the tool graph.

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

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

Gives an explicit when-to-use rule ('Use it first when you only have a name') and an explicit next step ('Pass either to br_stock, br_history, br_fund or br_options'). It also warns that funds have distinct ids per source, which tells the agent not to deduplicate across sources.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), so the description focuses on genuinely new behavior: the two sources are returned as separate non-merged blocks because their fields differ, prices are denominated in Rial, and the schema notes partial failure for source=all. It doesn't discuss response size, latency, or rate limits, which keeps it short of 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.

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

Four sentences, front-loaded with the core purpose, then usage routing, then next-step pointers. The per-source field inventory is slightly long but does real work in telling the agent why output is duplicated rather than merged.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates by characterizing what each source returns and why the shapes differ, plus currency and the partial-failure contract. That is enough for an agent to call it correctly and interpret the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the enum values, symbol formats (فولاد, name fragment, ISIN) and order_book semantics are already documented. The description only reinforces that ETF symbols resolve on Mofid; it adds little meaning beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Show one stock ... in detail') and enumerates what is returned: price, ratios, returns, real vs legal flows, from Mofid and Agah. It also distinguishes itself from list-orientation siblings (br_stocks) and from br_fund for Agah funds.

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

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

Explicit sequencing is given ('Use it after br_search') along with named alternatives for adjacent needs: br_history for candles, br_stock_events for dividends, br_technical for signals, br_fund for an Agah fund. The agent knows both when to pick this tool and where to go instead.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and openWorld, so the safety profile is covered. The description adds genuinely new context beyond that: the single upstream source (Agah), the dividend unit and fiscal-year scoping, and the freshness basis for shareholder data ("latest disclosed"). It omits failure behavior for an unknown symbol and whether history depth is bounded.

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

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

The first sentence front-loads the four returned data types, followed by short, scannable lines for source and unit conventions. Nothing is wasted, though the trailing 'Dividends are per share...' sentence mixes two unrelated output conventions and could have been folded more tightly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only, two-parameter tool with no output schema and full annotation coverage, the description supplies what an agent needs: returned content, data provenance, unit conventions, and call sequencing. Remaining gaps (history depth, behavior on ambiguous symbol matches) are minor relative to the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already documented, including the holders default and its meaning. The description adds no parameter-level detail beyond the schema — the unit and freshness notes it provides concern output values rather than inputs. Baseline 3 is appropriate where the schema carries the parameter burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb (list) and enumerates the exact resources returned: cash dividend history, capital increases, exchange notices, and major shareholders. That is far more informative than the title alone. It does not, however, explicitly distinguish itself from br_announcements, which by name likely also covers exchange notices.

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

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

"Use it after br_search or br_stock" gives a concrete sequencing rule, and "Source: Agah only" states a data-coverage constraint the agent should know before relying on results. It stops short of naming alternatives (e.g., br_announcements for notices, or br_stock for quote-only lookups) or stating when-not to call it.

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

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

Annotations already declare read-only, idempotent, non-destructive, so the safety profile is covered. The description adds value the annotations cannot: the ~750-symbol universe, the single-source (Agah) constraint, and the Rial currency unit for money and prices. It does not describe output shape or ordering ties, which is the remaining gap.

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

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

Front-loaded with the core action and kept to a few tight sentences, but the instruction "Then call br_stock for one symbol" appears twice, which is pure duplication in an otherwise economical definition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Six optional parameters all have defaults, no output schema exists, and the description still conveys enough to call correctly: what gets ranked, in what unit, from which source, and how to drill down. Missing detail on default sort behavior in prose and on the returned list contents keeps it short of perfect.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 83%, so the baseline is 3, but the description earns above that by defining the two least self-explanatory ranking fields: net_money_flow as signed net inflow/outflow and buyer_power as the individual buyer-vs-seller average-size ratio. Fields like queue_value and volume_vs_avg in the sort enum remain unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource with scope: rank all listed stocks (~750) by a named set of metrics. It also delineates siblings by naming br_market_top as the Mofid equivalent and br_stock for single-symbol follow-up, so an agent can pick this tool without opening any schema.

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

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

Gives concrete user-question triggers ("biggest gainers today", "most traded", "where is money entering") plus a source constraint (Agah only; Mofid rankings live in br_market_top). The next-step routing to br_stock for a single symbol is explicit rather than left to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world behavior, so the bar is lower. The description adds real context beyond them: a source restriction to Agah, the derivation of the action value from buy/sell counts, and a disclaimer that it is an automatic tally rather than advice. It does not cover latency, coverage gaps for symbols with insufficient history, or result shape, 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.

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

The purpose is front-loaded in the first sentence, followed by source/routing notes and then output semantics. Every sentence carries information, though the line-broken layout and the parenthetical enumerations are slightly denser than needed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

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 properly takes on the job of explaining the return value by defining the action scale (-2 to 2) and how it is derived. Combined with the source restriction and sibling routing for a 2-parameter read-only tool, nothing essential for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both target and timeframe are already documented, including the enum meanings. The description adds no syntax, format, or validation detail for either parameter; its explanation of the action scale is about return values, not inputs. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

"Show Agah's technical-indicator summary (moving averages and oscillators vote, RSI, MACD and others) for a stock or industry" gives a specific verb, resource, and content list. It explicitly distinguishes itself from the sibling br_scores, which only offers a coarse Buy/Neutral/Sell rating, so an agent can route between the two without opening either schema.

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

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

It states sequencing ("Use it after br_stock") and a source constraint (Agah only, with br_scores named as the alternative for Mofid data). It lacks an explicit when-not-to-use clause, but the alternative routing is clear enough to choose correctly.

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