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 then adds genuinely non-obvious behavior: the board is live intra-session but freezes at the last session after close, with `time`/`date` as the staleness signal. It also enumerates the returned fields and units (value in Rial), which is real added value. It stops short of describing pagination or what happens when `search` matches nothing.

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 and the live/closed behavior are front-loaded, and the sibling redirect is placed last where it belongs. The middle list of returned fields is the one long clause, but it earns its place since there is no output 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 correctly takes on the job of listing return fields and their units, and it explains the live-vs-frozen-session distinction an agent needs to interpret freshness. All parameters carry schema descriptions, so the gaps are minor: no note on sort/search interaction or behavior when no rows match.

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 both enums are documented in the schema, so the baseline is 3. The description adds no parameter-level meaning — it never mentions kind, sort, limit or search, so it neither compensates nor detracts.

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+resource: a market-view board at cdn.ime.co.ir returning best bid/ask and current quote fields, with the scope ('where a fund or certificate trades now') spelled out. It distinguishes itself from ime_securities by naming that sibling as the daily-history alternative, so an agent can route 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 the positive case ('use it to see where a fund or certificate trades now') and names one explicit alternative ('For daily history over a range use ime_securities'), which covers the most likely confusion. It does not address the other plausible siblings (ime_certificates, ime_options, ime_market_summary), so routing among the full set is still partly inferred.

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?

The annotations already declare the tool as read-only, idempotent, non-destructive, and open-world, so the safety profile is covered. The description adds useful behavioral context about hierarchical traversal and downstream id usage, though it does not discuss return size, caching, or rate limits.

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 resource and hierarchy, then immediately gives the calling pattern and downstream usage. Every sentence contributes useful information, and the parenthetical examples clarify category levels without excessive length.

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 two-parameter, read-only taxonomy lookup with full schema descriptions and no output schema, the description is complete enough for an agent to call it correctly. It covers the hierarchy, argument combinations, returned ids, and how those ids feed other 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 the parameter baseline is already strong. The description adds meaningful traversal semantics beyond the schema by explaining that no arguments returns main groups, main_cat returns groups under it, and main_cat plus cat returns subgroups, with concrete examples of each level.

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: listing the exchange's commodity groups, including the hierarchy of main groups, groups, and subgroups with ids. It is clearly distinguishable from sibling tools such as ime_trades and ime_price_history because it serves as the taxonomy lookup used to obtain their category ids.

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 explains the three call patterns: no arguments for main groups, main_cat for groups, and main_cat plus cat for subgroups. It also tells the agent how the returned ids should be used in ime_trades, ime_supply, and ime_price_history, leaving little ambiguity about when this tool is needed.

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 genuinely useful behavior beyond that: the default window is the last 30 days capped at 90, and prices are quoted in Rial per certificate unit (~1 gram for gold bar, one coin for GoldCoin). It stops short of describing pagination, row limits in the list mode, or what 'active customers' counts.

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 and both modes, and the sibling routing is placed last where it belongs. Slightly redundant: the opening sentence's commodity list is restated as 'gold bar / gold coin / silver certificates' in the next line, costing a clause without adding 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 carries the return-shape burden and does it well, enumerating first/high/low/last, settlement, change, volume, value, open interest and active customers. Unit and currency semantics are covered. What's missing is list-mode sizing or truncation behavior for the all-certificates branch.

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 still adds real semantics: it explains that `commodity` switches the tool between summary and history modes, and that dates default to the last 30 days with a 90-day maximum — a constraint absent from the schema's date descriptions.

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 the specific resource (continuous commodity deposit certificates on the IME) and enumerates the covered commodities, then splits the tool's two behaviors cleanly: list-all with latest day stats vs. per-commodity history. It explicitly routes fund and saffron-certificate symbols to ime_securities, so an agent can distinguish it from siblings 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 an explicit conditional: without `commodity` you get every certificate's latest day; with `commodity` you get that certificate's day-by-day history. It also names the alternative tool (ime_securities) and the symbol class that belongs there, which is exactly the when-not-to-use guidance most definitions omit.

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 genuinely useful behavior the annotations cannot: a 14-day default window and a hard 45-day cap. It stops short of describing granularity edge cases (holidays, missing days, timezone) or response ordering.

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 paragraphs: the first states what it returns, the second states when to use it and the operative constraints. Nothing is repeated from the schema verbatim and the constraint (45-day max) is placed where an agent will hit it 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 burden of explaining returns, and it does so adequately — day-by-day series of value and volume with units stated. Missing only minor details such as whether empty days are included and the ordering of the returned series.

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 date formats plus Persian/Gregorian flexibility are already documented per-parameter, so the baseline is 3. The description does add meaning the schema lacks — that value is in million Rial and volume is tonnes/contracts/units depending on market — which is a real complement to the enum, though market-specific unit mapping is the only true addition.

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 the resource precisely — day-by-day value and volume for one market over a date range — and the parenthetical 'the site's market chart' anchors it to a concrete artifact. It implicitly separates itself from ime_price_history (price, not volume/value) and ime_market_summary (snapshot, not series), but never names a sibling explicitly.

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 a concrete when-to-use framing ('Use it for trends') with a worked example question about physical volume over the last month, which tells the agent the intended shape of request. It offers no exclusions or named alternatives for point-in-time or per-security queries, leaving that routing 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 the description still adds real context: dates default to today in Tehran time, the range should be kept short, and units (million Rial, tonnes). It does not say anything about cost/limits when a wide range is requested beyond 'keep it short', which is the only remaining gap for a read 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-loads the scope sentence, then usage, then caveats — every sentence carries information (units, defaults, alternative). Slight drag from the parenthetical hall enumeration and the compressed 'offer_volume' clause, but no padding.

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 carries the burden of explaining returned values — and it does, naming units for values, volumes, offer_volume, and the USD settlement rate. Nothing an agent needs to call this 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 documents both dates' accepted formats, so the baseline is 3; the description adds the default behavior ('dates default to today (Tehran)') and a practical range-size constraint that the schema does not express.

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 resource (exchange-wide trade value and volume) with its exact breakdowns (by market, by physical-market hall, plus USD rate) and a date range. An agent can distinguish it from a single-market or single-security tool 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 concrete use cases ('how big was trading this week', 'which hall led') and explicitly routes the alternative: 'For a day-by-day series use ime_daily_totals.' Both the when and the when-not are present.

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. The description adds genuinely useful context (Persian-language text, returned fields), but says nothing about result ordering, recency window, or how the default limit of 10 behaves in practice.

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, resource and payload front-loaded, and the Persian-language note is a high-value detail placed where it will be read. Slight redundancy between the purpose statement and the use-case list 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?

With no output schema, the description correctly compensates by naming the returned fields, and annotations carry the safety semantics for a one-optional-parameter read tool. What remains thin is routing guidance relative to ime_weekly_reports, the closest sibling.

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 and the schema documents it at 100% coverage with default and bounds, so the schema does the heavy lifting. The description adds no meaning beyond it (e.g., whether limit truncates the newest items first), which is the baseline 3 case.

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 resource (the exchange's news archive) and enumerates the returned fields (title, lead, date, link), so the agent knows exactly what it fetches. It does not, however, distinguish itself from the ime_weekly_reports sibling, which it implicitly claims territory over via 'weekly trading reports'.

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 positive use cases (announcements, weekly trading reports, new listings) but never says when NOT to use it or names an alternative. The 'weekly trading reports' example actively invites confusion with the ime_weekly_reports sibling tool, with no rule for choosing between 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 declare readOnly/idempotent/non-destructive, and the description still adds real context: the 10-day range cap, the 45-day history cap, Rial currency for strike/value/prices, and the full set of returned columns. It does not cover pagination behavior or what happens when the 10-day cap is exceeded, 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?

Three dense sentences, front-loaded with the resource and the two primary modes, then return fields, then the sibling pointer. No filler, and the mode-selection rules come before the column inventory.

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 enumerates the returned fields (call/put type, underlying, strike, expiry, OHLC/last, settlement and change, volume, value, open interest), and it discloses both the 10-day and 45-day limits. Nothing an agent needs to invoke this 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 already 100%, but the description adds cross-parameter semantics the schema does not state: the 10-day maximum on date_from/date_to, the 45-day history horizon when contract is set, that contract must be a code from an earlier answer, and that an omitted date range means the latest trading day. This is meaningfully beyond the per-field descriptions.

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 ('Options on gold, gold coin, gold funds and saffron futures') plus the two modes (one day's board vs. one contract's history), and explicitly names the sibling ime_daily_totals(market="options") for market-wide totals. An agent can distinguish it from ime_board, ime_daily_totals and ime_price_history 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 explicit branches: no dates → latest trading day; date_from/date_to (max 10 days) → every day in range; contract → that contract's day-by-day history up to 45 days. It also names the alternative tool and the condition ('market-wide option totals per day') that selects 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 readOnly/idempotent, but the description adds the non-obvious behavior an agent cannot infer: default window of the last 14 days, a hard 45-day cap, the trap that a wide filter silently returns only the 8 biggest symbols, and the fact that days without trades are absent from the series. Those truncation and coverage rules are exactly the kind of context structured fields don't carry.

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 tight sentences, front-loaded with the resource and returned fields, then the usage case, then the constraints. It is dense but every clause carries information; only the slightly run-on constraint sentence could be split for readability.

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 naming all returned measures, and it covers the defaults, the maximum range, and the sparse-day caveat. An agent has enough to call it correctly and to predict what comes back, without needing anything else.

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 baseline is 3, but the description adds real semantic value: the 14-day default and 45-day ceiling for date_from/date_to, and the behavioral consequence of a broad filter. It still leaves main_cat / sub_cat / producer / cat unexplained beyond what the schema says (all four share an identical 'category id' description), which is the main residual gap.

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 resource (daily price series) at a specific grain (per symbol, over a date range) and even enumerates the returned measures (low, high, volume-weighted average, volume). It also relates itself to the sibling ime_trades ('Built from the trade list... Prices as in ime_trades'), so an agent can tell it apart from the raw-trades tool 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 a concrete use case ('how did hot sheet / rebar / PE prices move this month') and tells the agent how to narrow results via sub_cat or search. It stops short of explicitly saying when to prefer ime_trades or ime_trade_stats instead, so routing against alternatives is implied rather than declared.

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. The description adds the workflow link (the returned id is the value other tools expect) but says nothing about result behavior such as empty result sets, multiple matches, or ordering.

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, no filler: the first defines what is found and why, the second states exactly how the output feeds sibling tools. The purpose is front-loaded before the integration detail.

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 carries the key return information (a producer id) and its downstream use. Minor gaps remain around match ambiguity and empty results, but nothing critical to calling it 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 schema already documents both query (partial name, Persian or English, with an example) and limit (1-50, default 20). The description adds no meaning beyond that, 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 (find producers/suppliers on the exchange by name) plus the concrete outcome (get the producer id). It also implicitly separates itself from siblings by declaring itself the id-lookup step rather than a data-fetch step.

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 frames usage as a prerequisite step for ime_trades, ime_supply and ime_price_history, so the agent knows to call this first and pass the id along. It stops short of stating failure or no-match handling or when another lookup tool (e.g. ime_securities) would be preferred.

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 goes further by disclosing the 45-day range ceiling, the implicit 'latest day' fallback, the exact row contents (close, last, change vs previous close, trades, volume, value, low, high) and the unit convention (Rial per unit). Those are real behavioural constraints an agent cannot infer 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 definition, then default behaviour, then return shape, then sibling routing — a logical order for an agent to consume. Dense but every sentence carries information; nothing repeats the name or 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?

With 6 optional parameters, no output schema, and a 100%-covered schema, the description closes the remaining gaps: what a row contains, what units prices are in, and what happens when dates are omitted. Nothing needed to invoke the tool 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%, so the baseline is 3, but the description adds genuine semantics the schema does not: the date pair operates as a range with a hard 45-day maximum and a 'no dates means latest day' default, which changes how an agent should populate date_from/date_to. It does not elaborate on how sort interacts with a date range, so not quite 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?

Names a specific resource (daily trades of salaf, commodity deposit certificates and commodity funds) with a concrete verb-and-scope framing, and gives two natural-language queries that pin down the intent exactly. It also explicitly differentiates from ime_certificates and ime_board, so an agent can route without opening sibling 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 default behaviour with no dates (latest trading day), the behaviour with dates (every day in range, capped at 45), and names two alternatives with the exact condition that selects each — gold bar/coin/silver continuous certificates go to ime_certificates, live bid/ask goes to ime_board. That is explicit when-to-use, when-not-to-use, and where-else.

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), and the description adds real behavioral context beyond them: the implicit date window defaults and 45-day cap, that dates are offer dates rather than trade dates, the field set returned per offer, offset-based paging, and the premium/export market variants including that export is priced in dollars. That is substantive disclosure for a read 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?

The purpose is front-loaded in the first line, followed by usage, then returned fields, then filtering/paging, then the sibling pointer. The field enumeration is dense but justified because there is no output schema, and the cross-reference to ime_trades replaces several sentences of filter documentation.

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 the returned fields, and it covers the date-window behavior, paging, market variants, and the relationship to ime_trades. For a 10-parameter read tool with full schema coverage, an agent has everything needed 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 coverage is 100%, so the baseline is 3; the description earns a point by adding meaning to the market enum (premium contracts expose `premium_price`, export is the Kish export hall priced in $) and by clarifying that date_from/date_to refer to offer dates. It does not resolve the odd schema wording on `producer` (described as a category id), deferring instead to "Filters as in ime_trades," which leaves that one filter ambiguous.

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 and resource ("List supply offers") plus the domain meaning (اطلاعیه عرضه) and the content of each row (what is for sale, session, volume, base price). It also explicitly distinguishes itself from the closest sibling: offers are forward-looking, while "After the session, ime_trades shows what actually sold."

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 exact question this answers ("what will be offered tomorrow / next week"), the default and maximum date window (today to +7 days, at most 45 days), and names the alternative tool with the condition that selects it (ime_trades after the session). It also points to ime_trades for filter semantics, leaving little 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 read-only/idempotent/non-destructive, and the description still adds substantial context beyond them: the 45-day window and today-default, the premium market's lack of a producer filter, and the caveat that subsidiary rows publish no price or value. Field semantics (price = volume-weighted close, value_k_rial = price x volume in thousand Rial, prices Rial/kg for tonne goods) are exactly the interpretive detail an agent would otherwise get wrong.

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 trigger phrases, then constraints, then field semantics, then sibling routing — a sensible order with no filler sentences. It is a dense single block, though, and the mid-sentence mix of Persian terms and backticked field names makes it slower to scan than it needs to be.

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, yet the description explains the returned columns, their units, how `value_k_rial` is derived, and which fields are absent for subsidiary rows — enough for an agent to interpret results correctly. Combined with the date-window and filter-source guidance, nothing needed 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% (baseline 3), and the description goes beyond it by naming the id sources per filter (main_cat/cat/sub_cat from ime_categories, producer from ime_producers) — which actively corrects the schema's copy-paste error describing `producer` as a category id — and by adding the 45-day/dates-default-to-today rule that appears nowhere in the schema. Minor gap: it does not touch `sort` or `limit`, though the schema documents those adequately.

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 + returned fields: "List commodity trades (price, volume, supply, demand, buyer broker) for a date range, with totals." The closing sentences explicitly separate it from ime_price_history (single-product series) and ime_market_summary (market-wide totals), so an agent can pick it out of a 14-tool family 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?

Concrete trigger phrasings ("what traded today", "steel prices this week", "who bought what") and explicit routing to siblings: ime_price_history for a price series, ime_market_summary for market totals, ime_categories/ime_producers for filter ids. It also states the operating constraint (max 45 days, defaults to today Tehran) that determines whether the tool is usable for a given question.

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 behavior, but the description adds meaningful operational context: Tehran-default dates, a 45-day maximum window, thousand-Rial values, and the volume caveat when group trades do not share one unit. It could be a 5 with a bit more about the returned ranking shape, but it is substantially informative.

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, followed by concrete examples, constraints, and sibling alternatives. The prose is compact for a 10-parameter analytics tool and every sentence carries useful selection or interpretation guidance.

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?

Given 10 parameters, no output schema, and rich annotations, the description supplies the key context an agent needs: ranking metric, market share, date constraints, value unit, volume caveat, and alternatives. The schema handles the remaining filter details, so nothing essential is missing 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 baseline is 3, but the description adds important semantics beyond the schema: date defaulting, the 45-day maximum range, filter parity with ime_trades, and value/volume interpretation. It does not clarify every filter parameter or mention contract in the prose list of group_by values, so it falls 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?

States a specific verb, resource, metric and scope: rank producers/commodities/brokers/halls by traded value over a date range with market share. It explicitly distinguishes itself from ime_trades and ime_price_history, so an agent can select it without opening sibling 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 direct use cases and names the alternatives for adjacent jobs: single trades go to ime_trades, and one product's price history goes to ime_price_history. It also states date defaults and the 45-day cap, leaving little ambiguity about when to use 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 readOnly/idempotent/openWorld/non-destructive, so the safety profile is covered. The description adds genuinely useful behavior the schema cannot: reports are PDFs in Persian, only links are returned, and the newest-first ordering. It stops short of describing pagination depth or what metadata accompanies each link, which keeps it at a 4.

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 what is returned, then routing guidance. The parenthetical Persian gloss and the repeated 'newest first' are mild redundancy but each sentence still carries routing or behavioral value.

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-parameter, no-output-schema listing tool, the description supplies what an agent needs: return shape (PDF links), language, ordering, and where to go for actual figures. Only the presence of non-link metadata per report is left unspecified, a minor gap given no output schema exists.

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 (year range 1380-1500, limit 1-60 newest first) are already fully documented. The description's 'newest first' merely echoes the limit description and adds no new format or semantics, 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+resource (list weekly market reports), the ordering (newest first), and the payload (PDF link per report). The Persian term and the explicit 'this tool only lists links, it does not read them' make the unit of return unambiguous versus every 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?

Gives an explicit use case ('find the official weekly summary of a week') and names the alternatives with the condition selecting them: ime_market_summary or ime_trades for numbers, ime_news for announcements. It also states the negative case (does not read the PDF), so the agent knows when this tool alone is insufficient.

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