Trade statistics by group

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.