Trades on the exchange

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.