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

Annotations already establish read-only, idempotent, open-world access, so the description focuses on what those flags cannot convey: newest-first ordering, Jalali dates, that announcements return a PDF url while news returns an id, and that returned text is data rather than instructions. That last point is a meaningful prompt-injection warning absent from any structured field.

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 written sentences: purpose and ordering first, then use cases, then a compact per-source return-shape and safety note. Every clause carries information an agent needs before calling.

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-value burden and does so at a per-source level (url, id, message text). Missing are pagination limits beyond what the schema states and the fact that all six parameters are optional, meaning an unfiltered call returns the newest announcements across the board.

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 itself documents page size, enum meanings, and the Jalali date pattern, so the baseline is 3. The description adds only the newest-first ordering and repeats that dates are Jalali; it does not explain how `query` and `symbol` interact or whether `symbol` is silently ignored for news and market_messages beyond the schema's brief note.

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 opens with a concrete verb plus resource ('Search Fara Bourse announcements, news and market messages') and names the three sub-corpora it spans, which no sibling covers. It also distinguishes itself from ifb_article by noting news items carry an `id` for that 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?

It gives three explicit use cases (why a symbol is halted, when a bond/IPO starts trading, what the exchange announced on a topic) that map directly onto the source enum. It stops short of naming alternatives such as ifb_halted or ifb_ipos as substitutes for those questions, so routing is implied rather than 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 declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds value by disclosing the return shape ('headline, publication time and body text') — the only place this is stated, since there is no output schema. It does not mention rate limits, auth, or whether body text is truncated for long articles.

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 sentences, zero filler: what it reads, what it returns, and how to get the id. The essential use-after guidance is placed last and correctly follows the purpose statement.

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 single-parameter read tool with strong annotations and no output schema, the description covers purpose, return contents, and prerequisite routing. Nothing an agent needs in order to invoke 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% and the id parameter already documents its origin and an example value (20152), so the schema carries the full burden. The description only says 'one article' and adds no format, range, or error-handling guidance beyond the schema — 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 ('Read the text of one Fara Bourse news article') and enumerates the content classes it covers (weekly trading statistics, listings, rule changes). The singular 'one article' plus the stated return fields immediately distinguishes it from list-style siblings like ifb_announcements.

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 tells the agent it must first obtain the id via ifb_announcements(source="news"), which is a concrete prerequisite and effectively names the companion tool. It does not state any when-not condition or contrast with other content-fetching siblings, but the sequencing guidance is unambiguous.

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 description is free to add what structured fields cannot: that capital increase amounts are raw as displayed with units unstated (probably millions of rial) and that windows are short Jalali "from to" strings while other dates are Jalali. Those are exactly the caveats that prevent an agent from misreading the output.

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-loads purpose, then usage examples, then data caveats, then next-step routing — a sensible order with little waste. The line breaks fragment the prose slightly and the caveat sentence is dense, but every sentence carries 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?

With no output schema, the description should convey return shape; it implies rows of symbols plus amounts/windows and documents the date and unit quirks, which is the main risk. It does not state the fields present per row or default ordering, leaving a modest gap for a list 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 description coverage is 100% and the enum values are already documented in the schema itself, so the description rightly does not repeat them. It adds no parameter-level detail beyond what the schema provides (no note on limit/ordering behavior or symbol_contains matching rules), 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 ("List corporate actions on Fara Bourse") and immediately enumerates the three/four covered categories, which map exactly to the enum values in the schema. An agent can distinguish this from ifb_ipos or ifb_underwritings 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?

Gives three concrete user-question framings ("which companies are raising capital and when is the rights window", "which symbols changed board recently", "what listed here lately") that map to actual invocation, plus an explicit follow-up chain (symbol -> ifb_search -> ifb_instrument/ifb_quote). It stops short of naming exclusions, e.g. that detailed IPO mechanics belong to ifb_ipos rather than this 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 cover the safety profile (readOnly, idempotent, non-destructive, open world), so the description is free to add genuinely new context: result-set size expectations, that dates are Jalali, and that authoritative exchange wording lives elsewhere. The only blemish is the "up to 50 rows" claim, which sits awkwardly against the schema's "10 rows per page" note for this 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?

Three short sentences, front-loaded with the capability, then routing, then practical constraints. Every sentence carries information, though the quoted example phrasings overlap with the usage sentence that precedes them.

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?

No output schema, but the description tells the agent what the rows contain (symbol, date, reason), how large the result typically is, and how to interpret dates — enough to call and interpret the tool correctly. The unresolved page-size/row-count ambiguity is the remaining 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 description coverage is 100%, with both parameters fully documented including the kind enum and page bounds, so the baseline is 3. The description adds little parameter-level detail beyond echoing the two modes and noting Jalali dates, and its page-size remark mildly conflicts with the schema rather than clarifying it.

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 — listing halted symbols on Fara Bourse with halt date and reason, plus the second mode of issuers flagged for weak disclosure. This is clearly distinguishable from siblings like ifb_announcements or ifb_instrument.

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-phrasings that select this tool ("which symbols are stopped today", "why is X halted") and explicitly routes the exchange's own wording to ifb_announcements with the exact parameters to use there. Both the when and the when-not are named.

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), but the description adds real behavioral detail: results are newest-first, no-trade days are omitted rather than forward-filled, and ytm_pct appears only for bonds and treasury bills. It stops short of describing pagination or a hard cap beyond what the schema's 1-250 bound implies.

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, front-loaded with the return shape, then the bond/yield exception, then the routing hint. No sentence is redundant with another or with the schema.

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 burden of describing return values and it does: named fields, ordering, conditional ytm_pct, and the gap-handling rule. An agent can call this correctly and interpret the response without further information.

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 earns a bump by clarifying that history is per trading day with no-trade days dropped, which disambiguates what the 'days' count actually enumerates. The single-instrument scope is also made explicit, beyond the schema's own wording.

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 ('Get daily price history of one instrument') and enumerates exactly what is returned (first, high, low, close, volume per trading day). The mention of 'one instrument' and the yield caveat for bonds/T-bills separates it cleanly from siblings like ifb_index_history and ifb_yields.

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 use case with a concrete example ('how has اخزا301 moved this month') and redirects the adjacent need to the right sibling: 'For today's price use ifb_quote.' It also states the exclusion that no-trade days are absent, so the agent knows not to expect a gap-filled series.

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, so the safety profile is covered; the description adds genuinely new behavioral detail about the response shape — `latest` is the newest value, `changes_pct` compares against 1, 5, 21 and 250 trading days back, and `points` are newest-first. It stops short of stating limits such as rate limits or behavior when days exceeds available history (~4,100), which is why it is not 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 sentences, front-loaded with the core capability, then usage examples, then a compact field glossary. Every sentence carries distinct information and the sibling hand-off is placed last where it belongs.

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?

No output schema exists, and the description compensates by explaining the three return fields and their ordering. Combined with the fully documented 3-parameter schema and the annotation set, an agent has everything needed to call this 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 coverage is 100%, so baseline is 3; the description earns above baseline by pairing parameters with concrete call patterns (days=250, days=2000 + step="monthly") that show how the knobs interact. It doesn't add index-selection semantics beyond the enum, so it stays below a 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?

States a specific verb and resource ("Get the daily history of a Fara Bourse index since 2009") plus the scope of what is returned (day/week/month/year change). It distinguishes itself from siblings by routing intraday/turnover needs to ifb_market_summary, so an agent can separate it from ifb_market_summary or ifb_history 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 two concrete usage scenarios with actual parameter values (days=250 for a year-to-date question, days=2000 with step="monthly" for a long trend) and names the explicit alternative (ifb_market_summary) for the intraday case. When-to-use and when-not-to-use are both covered.

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 the safe read-only, idempotent profile. The description adds useful behavioral context beyond that: coupon_schedule rows contain per-paper rial amounts and the last row also repays face value, next_coupon is the first on or after today, and live=true triggers one extra 3 MB page and is slower. It does not discuss rate limits or partial-failure behavior, 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?

The description is front-loaded with the primary purpose and then adds routing and return-format details in a compact two-paragraph form. Every sentence carries information, though the second paragraph is dense and could be slightly tighter.

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 must explain return values; it does so for coupon_schedule, next_coupon, and the live-share case. It lists the basic instrument fields and covers the main edge behavior, but does not explain missing-instrument handling or other failure modes, leaving a small 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 description coverage is 100%, so the baseline is 3; however, the description adds genuine meaning beyond schema: it clarifies what live=true returns for a share (quote, price band, P/E, industry peers) and ties coupons=true to the detailed row semantics of coupon_schedule. It does not fully restate every parameter's behavior, but the added output-oriented context is valuable.

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 ('Describe one Fara Bourse instrument') and enumerates the returned fields (name, ISIN, market, coupon rate, maturity, issuer, guarantor, payment schedule). It clearly distinguishes itself from siblings like ifb_yields, ifb_search and ifb_quote by explaining when to call each.

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 explicitly says to use it after ifb_yields or ifb_search, and gives a concrete routing rule: pass live=true for a share to get the quote and peers in one call, otherwise call ifb_quote for live price and order book. This is exactly the kind of when-to-use and alternative-tool 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 this as a read-only, idempotent, non-destructive operation. The description adds valuable behavioral context beyond annotations: completed results are newest first, include price band end and volume/value traded, while pipeline results include valuation method, valuer, introduction meeting, offering date, and links.

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 with the core purpose, then structured around stage choice, next-tool routing, and filter scope. Every sentence adds actionable information with no wasted preamble.

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?

Although there is no output schema, the description explains what each stage returns, including sort order and key fields, and describes the follow-on workflow. Pagination and Jalali date syntax are handled by the input schema, so the definition is complete enough for correct invocation.

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 parameters in detail, giving a baseline of 3. The description adds useful semantics for the stage parameter and clarifies that filters apply only to completed results, but it does not add much about page, date, or offering_type beyond the schema.

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: 'List Fara Bourse initial public offerings (IPOs).' It immediately distinguishes finished IPOs from upcoming/under-way ones, giving an agent a clear sense of what this tool returns compared with generic instrument tools.

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 explicit routing guidance: use stage=pipeline for upcoming IPOs and stage=completed for historical IPOs, and it states that filters apply only to completed results. It also tells the agent to take the symbol onward to ifb_search, then ifb_instrument or ifb_quote.

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 and open-world, so the bar is lower, yet the description still adds real behavior: totals refresh during the session while per-market figures lag to the last archived session, and all values are in rial. It doesn't discuss failure modes or per-call cost, keeping it under 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 one-line summary, then usage, then freshness caveats, then a short glossary of `markets` and `bond_indices`. Dense but every clause carries information; the parenthetical Persian board names are justified since they map to returned keys.

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 enumerating exactly what is returned, defining the `markets` boards and `bond_indices` families, and stating units and freshness semantics. An agent can interpret every part of the response without further lookups.

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 single `top` parameter is fully documented with range and default. The description only echoes it via 'top movers' without adding format or interaction detail, so the schema does the heavy lifting – baseline 3.

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?

Specific verb ('Summarise') plus resource ('the Fara Bourse session') and an explicit inventory of contents: index, bond indices, total turnover, and per-market value traded with top movers. An agent knows exactly what it gets, though the closest sibling (ifb_market_watch) is never named or distinguished.

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 for 'how is the market today'" gives a clear triggering context, and the note about totals refreshing intraday versus per-market figures coming from the daily archive tells the caller when the data is current. No explicit exclusions or named alternatives are given, so it stops 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.

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

Goes well beyond the readOnly/idempotent/openWorld annotations: it discloses the data source (same feed as the site's market watch page), payload size (~3 MB), cache TTL (30 s), a cost warning ("call it sparingly"), and stale-data behavior outside trading hours (shows the last session). It also explains two return fields, `breadth` and `as_of`, that the agent would otherwise misread.

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 dense sentences, zero filler, front-loaded with the what before the when before the cost warning. Every clause is load-bearing: feed identity, size, cache, off-hours behavior, and the `id` handoff all change how an agent calls or reuses the tool.

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 does enough for a 7-param list tool: it explains the two aggregate fields, notes the 3 MB/cached payload, and explains the `id` handoff. It stops short of describing row shape or pagination behavior beyond `limit`, which leaves some guesswork on large responses.

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 enum/limit/sort descriptions already carry the semantics, so the schema does the heavy lifting and baseline 3 applies. The description adds nothing about the seven parameters — notably it never mentions the `board`, `status`, or `traded_only` knobs that would map to its own example queries.

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 the live Fara Bourse market watch") and enumerates exactly what each row carries: price, change, volume, best bid/ask. It also scopes the tool (ranked and filtered, ~1,200 symbols) so it is distinguishable from a single-instrument tool at a glance.

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 example intents ("top gainers today", "most traded symbols", "what is trading in the second market") and routes follow-up detail work to ifb_quote and ifb_instrument. However it recommends itself for "which symbols are halted" while a dedicated sibling ifb_halted exists, and it never distinguishes itself from ifb_market_summary — that overlap is left for the agent to guess.

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), and the description adds genuinely non-derivable behavior: units (rial per paper/share, market_value in rial), stale-after-hours semantics (shows the last session outside Sat-Wed 08:45-12:30 Tehran), empty order-book levels being dropped, and bond levels carrying per-price yield. That is exactly the context annotations cannot express.

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 what it returns, then usage, then units, then edge cases. Every sentence carries a distinct, load-bearing fact with 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?

For a single-parameter, read-only snapshot tool with no output schema, the description covers return contents, units, staleness behavior, and data-shaping quirks. An agent could call it correctly and interpret the response without further guidance.

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?

With one parameter at 100% schema coverage, the schema already documents that the id comes from ifb_search or ifb_yields and accepts an exact trading symbol. The description restates units but adds no new constraint, format, or edge case for the parameter, 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 ('Get the live trading data of one instrument') and enumerates exactly what comes back: last/closing price, change, volume, value, order book, and YTM for bonds. The word 'live' plus the 'what is it trading at now' framing implicitly separates it from the historical sibling (ifb_history) and the static profile sibling (ifb_instrument).

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 a clear positive use cue ('what is it trading at now' and 'best bids and offers') and indirectly routes the agent to ifb_search/ifb_yields for the instrument id. It never names a sibling it should not be used instead of, so there is no explicit exclusion, but the selection context is unambiguous.

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/non-destructive, so the bar is lower, and the description still adds genuinely non-obvious behavior: trading-board symbols carry a trailing digit the yields table omits (اخزا301 vs اخزا3011), so a stem search plus reading names is required. It does not say how results are ordered or what a match record contains, which keeps it below 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 purpose, then usage, then the alternative — a sensible order with no filler sentences. The parenthetical asset-class list and hyphenated wrap make it slightly denser than necessary, but every clause carries 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 2-param read-only lookup with no output schema, the description covers purpose, the id-producing role, a real matching pitfall, and the sibling alternative. Minor gap: it never characterizes the return (list of instruments with id/symbol/name), though 'read the names' implies it.

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, but the description adds meaning the schema lacks: `query` is a STEM (partial), Persian, and matches may not be exact due to the digit-suffix quirk, implying the agent should read returned names rather than assume a hit. `limit` is left entirely to the schema, which is acceptable.

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?

Specific verb+resource: 'Find Iran Fara Bourse instruments ... by symbol or name', with the asset classes enumerated. It also names the sibling it is not (ifb_yields), so an agent can distinguish it 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?

States the primary job explicitly: turn a symbol into an `id` that every other ifb_ tool requires, which is a clear when-to-use condition. It also routes away from itself for yield-based bond lookups ('use ifb_yields instead') and gives a concrete workaround for the digit-suffix mismatch.

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 state that this tool is read-only, idempotent, non-destructive, and open-world, so the description does not need to explain safety. It usefully adds behavior that annotations cannot convey: values are full numbers in rial even though the source site abbreviates with a B suffix, and rows are newest-day-first. Ordering and units are real additions, but rate limits and the shape of the response are not covered.

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 short sentences put what the tool returns first and when to use it second. No filler or repetition, and the unit caveat is packed into a compact parenthetical.

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?

No output schema exists, so the description has to cover return values; it does so by describing the trading-value breakdown, row ordering, and units. One ambiguity remains: the schema notes 10 rows per page, but the description never says whether pagination walks across days or across investor/type rows for a single day. That matters for correct paging.

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?

With schema description coverage at 100%, the schema fully documents both the 'by' enum and the 'page' bounds. The description gestures at the 'by=investor' dimension ('by who bought and sold') and at ordering, but adds no syntax or format detail beyond what the schema already supplies. The baseline score of 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?

The description names a specific verb and resource: daily trading value of Islamic financial securities (sukuk, treasury bills) broken down by buyer and seller. It is easy to separate from siblings such as ifb_yields or ifb_quote, which cover different datasets. It stops short of naming an alternative, so it is clear but not fully differentiated.

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?

The second sentence supplies a clear use case: observing central-bank open market operations and bank or fund activity day by day. That context is enough for an agent to choose this tool over an unrelated sibling. The description gives no explicit exclusions or mentions of alternatives, which keeps it from a 5.

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-only open-world call, so the description's job is narrower and it delivers: sorted newest first, row contents enumerated (issuer, security type, subscription dates, count, rial amount, industry). It does not mention total counts, pagination limits, or whether the list is complete or truncated.

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?

Scope and ordering are front-loaded in the first sentence, usage and next-step routing follow. The enumerated row fields are dense but each maps to a real output column; no filler sentences.

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 return-value burden by enumerating row fields and ordering, which is what an agent needs to decide if results answer the question. Minor gaps remain around result breadth (is the list exhaustive per page set?) and what `id` refers to exactly, though the forward routing hints at it.

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?

Only one optional parameter (`page`), and the schema already documents its default, bounds, and the 10-rows-per-page behavior at 100% coverage. The description adds nothing about paging strategy or how deep it is worth paging, so it sits at the schema-does-the-work baseline.

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 securities offered through underwriting on Fara Bourse') plus ordering ('newest first') and the local-language term پذیره‌نویسی, which disambiguates the concept. It does not explicitly contrast itself with the closest sibling, ifb_ipos, so an agent must infer that underwriting subscriptions and IPOs are different feeds.

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 a concrete use case quoted as a user question ('what was raised by underwriting recently') and notes the instrument classes covered (shares, sukuk, funds). It also routes forward ('Take the `id` to ifb_instrument or ifb_quote') but names no when-not condition or alternative list 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 cover the safety profile (readOnly, idempotent, non-destructive), so the description's added value is in describing what comes back: YTM in percent for horizons in days, at three time snapshots (now, one month, six months). That return-shape context is genuinely useful given there is no output schema, though it doesn't discuss gaps, interpolation limits, or empty-curve behavior.

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 sentences with no filler. The resource and scope come first, and the operational guidance (how to use it alongside ifb_yields) follows — properly front-loaded and scannable.

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 read with no output schema, the description supplies the essential context: what a curve contains, units (percent, days), and the three time snapshots. Minor gaps remain around response structure (e.g., how horizons are enumerated) but nothing that would block correct invocation.

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 the baseline is 4; there is nothing for the description to disambiguate, and it correctly implies a parameterless snapshot call by describing fixed instrument classes and time snapshots rather than configurable inputs.

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 ('Get Fara Bourse's fitted yield curves') and narrows scope by naming the model (Svensson/Nelson) and the three instrument classes covered. It also implicitly distinguishes itself from the sibling ifb_yields, which returns individual paper YTMs rather than a fitted curve.

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 a concrete use case — pricing a bond by comparing an `ifb_yields` YTM against the curve at the paper's remaining days — which tells the agent both when to call it and how it pairs with a sibling. It stops short of stating when *not* to use it (e.g., for raw historical yields, use ifb_history), so it's clear context without explicit exclusions.

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 read-only/idempotent safety profile, and the description adds genuinely non-derivable behavior: YTM is annualised percent computed from each paper's last trade, so `last_trade` must be checked for staleness, and never-traded papers simply have no YTM. It also states price units in rial with typical 1,000,000 face value. Only pagination/row-cap behavior beyond the schema's limit note is unaddressed.

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 one-sentence summary followed by caveats and routing; nearly every sentence carries information. The middle paragraph is dense with parentheticals, but nothing is 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?

For a 10-parameter, fully documented filter/sort tool with no output schema, the description supplies exactly the missing pieces: field meanings (last price, maturity, YTM), the staleness trap, the missing-YTM edge case, and cross-tool enrichment paths. Nothing an agent needs before calling it is absent.

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 enum/default descriptions already explain kind, YTM bounds, sort, and Jalali date format, so the schema carries the load. The description adds unit context (YTM annualised percent, price in rial, face value 1,000,000) that the schema lacks, but nothing parameter-specific beyond that.

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+resource: list fixed-income papers on Fara Bourse with last price, maturity and YTM, filtered and ranked. It also anchors itself to a concrete site table ("محاسبه بازده اوراق") and names the sibling tools it hands off to (ifb_instrument, ifb_quote), so an agent can place it precisely among the ifb_* family.

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 two concrete question shapes it answers ("best yield for a bill maturing before X", "which sukuk mature in 1406") and explicit follow-up routing to ifb_instrument for coupons/issuer and ifb_quote for the live book. It does not explicitly distinguish itself from ifb_yield_curve or ifb_sukuk_flows, which are the closest conceptual alternatives.

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