One stock or ETF in detail

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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