Screen stocks or funds by any column

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 instead spends its words on provenance (Agah only), data units (returns in percent, money in Rial, fund Nav in Rial), and the ETF column-naming trap where names ending in 2 are NAV returns and the rest are market-price returns. That is genuinely non-obvious behavioral context. It stops short of describing the row/response shape or any size or performance limits for a ~1,700-instrument screener, which keeps it off 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 verb, scope, and sibling routing in the first two sentences, then examples, then a dense units paragraph. Every sentence carries information, though the trailing units/column-family paragraph is compressed to the point of being easy to skim past, and the parenthetical dataset sizes sit awkwardly mid-sentence.

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, no-output-schema screener, the description covers the essentials an agent needs to call it correctly: which kind values exist, that columns must be looked up with list_columns, filter direction via max/min examples, and the unit conventions that determine whether a numeric threshold is sane. The remaining gap is that the return shape (rows of dicts keyed by column name) is never stated and there is no output schema to fill it in.

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 80%, so the baseline is 3; the description earns the bump by explaining that column names are the site's own and must be discovered via list_columns, and by clarifying units per column family (percent vs Rial) and the existence of FundType for funds. It still doesn't explain the interaction between sort/ascending/limit or what a default column set contains, which the schema also leaves vague.

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 set (filter, sort, compare) plus the resource (stocks or funds) and scopes it to the Agah screener universe with concrete sizes (~900 stocks, 330 ETFs, 475 funds). It explicitly contrasts itself with siblings: br_etfs for a plain ETF list with NAV gap and br_fund for a single fund.

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?

Usage is stated as concrete example queries ("stocks with P/E under 6 and ROE over 30", "best 1-year fixed-income funds", "ETFs with the lowest bubble"), and the alternatives are named with the condition that selects them (br_etfs for a plain list, br_fund for a single fund). Nothing about when to reach for this tool is left to inference.

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