Stock options: chain or one contract

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

Annotations already declare read-only, idempotent, non-destructive, open-world access, but the description adds substantive context the annotations cannot: the data source is Agah only, prices are quoted in Rial per underlying share, each row carries its contract size, and the single-contract mode returns margin, break-even distance, order book and real/legal flows. That is real disclosure of units and return content for a tool with no output 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?

The chain-versus-single-contract split is front-loaded in the first sentence and the closing sentence handles the prerequisite lookup. The block is a little dense with embedded quoted examples and an awkward source line, but no sentence is genuinely wasteful.

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 six optional parameters and no output schema, the description covers both operating modes, the fields returned in each, currency/units, and the data-source restriction. Pagination and ordering behavior around `limit`/`sort` remain unstated, which is the main residual gap.

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 83%, so the baseline is 3; the description goes past that by explaining the mode switch ("Pass `option` (an ISIN from the chain) for one contract") and by tying `underlying` to a search-first workflow. It still leaves the `sort` enum values and the `limit` cap unexplained, so it is good but not complete.

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 a specific resource (stock-option contracts, ~1,600) and a specific dual behavior: list the chain, or show one contract when `option` is supplied. It also states what each row carries (strike, expiry, moneyness, open interest, flows), so an agent can distinguish this from siblings like br_stocks or br_screener 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?

It gives concrete use cases ("options on Shepna expiring soon", "most traded calls") and an explicit routing rule: find the underlying with br_search first if the symbol is unknown. It does not, however, exclude or compare against the other market-data siblings, so the when-not-to-use side is only implied.

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