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

Annotations already declare this as read-only, idempotent and non-destructive. The description adds useful domain context: price field meanings, volume-weighted close, and Rial currency. It stops short of discussing market-session timing or stale-data caveats, but it adds enough beyond the annotations.

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 description is front-loaded with the core purpose, then adds field semantics and sibling routing in a compact block. Every sentence contributes useful information with no repetition or padding.

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 one-parameter quote tool with rich annotations and no output schema, the description gives enough context to call it correctly: it explains the main return fields, the currency, and where to go for related data. No critical details are 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% and the single symbol parameter is fully described with examples in the schema. The description does not add further parameter semantics beyond what the schema already provides, so it meets the baseline for a fully documented parameter.

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 states a specific verb and resource: latest price, daily range, volume and key facts for one TSE instrument. It also names sibling tools for adjacent tasks, so an agent can distinguish this quote lookup from order-book and historical-data tools.

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?

The description explicitly routes the agent to ts_order_book for bids/asks and ts_price_history for earlier days. It does not mention ts_market_movers or ts_search_symbols, leaving some sibling selection implicit, but the main alternatives are clear.

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

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: the return shape (close, high, low, percent change) and the ordering (newest first), which an agent needs to interpret results.

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?

Two tight sentences: the return payload and ordering come first, the lookup helper second. No filler, and the most decision-relevant information is front-loaded.

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 two-parameter read-only history tool with full schema coverage and no output schema, the description covers purpose, output fields, ordering, and the name-resolution path. Nothing essential is missing, though a note on grain (daily bars) versus sibling tools could sharpen it further.

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 both parameters are already documented with ranges and defaults. The description adds only that indices may be total, equal-weight, or sector-based, which slightly clarifies the domain of the 'index' argument but adds nothing about 'days'.

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 set (returns daily close, high, low and percent change) for a specific resource (a TSE index), and explicitly scopes the index universe (total, equal-weight, sector). This clearly separates it from ts_price_history (per-symbol prices) and ts_indices (name lookup).

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?

Explicitly routes the agent to ts_indices when the index name is unknown, which is the main prerequisite for calling this tool. It does not state when-not to use it (e.g. versus ts_price_history for equities), so it stops short of full alternative coverage.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered structurally. The description adds only the 'today' currency framing; it says nothing about result size, pagination, or what market state/trading totals actually contain. Adequate but thin given annotations carry most of the burden.

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?

Two sentences, both front-loaded with the highest-value information: what it returns, then when to use it and where to go for history. No filler or restatement of the title.

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 2-parameter, zero-required, read-only listing tool with no output schema, the description covers purpose, scope and sibling routing sufficiently to invoke correctly. Only minor gaps remain around result volume and the meaning of 'market state'.

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% – both `limit` ('max indices, strongest change first') and `query` (with Persian example fragments) are well documented in the schema. The description adds no parameter detail of its own, so the baseline of 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?

The description names the specific resource and its contents precisely: TSE total index, market state, trading totals, and every sector/market index with its change. It is clearly distinguishable from ts_index_history, though the verb is implicit (it describes the payload rather than saying 'lists'/'returns').

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 an explicit use case ('Use to see which sectors lead or lag today') and routes the agent to the correct sibling for historical values ('Pass an index name to ts_index_history for its past values'). It does not address overlap with other siblings like ts_market_movers, so it stops short of full when-not-to-use coverage.

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

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

Annotations already declare readOnlyHint/idempotentHint, so safety is covered. The description adds genuine domain context the annotations can't: only instruments that traded are listed, limit_up/limit_down flags mark a price stuck at its daily limit, and prices are denominated in Rial. It doesn't mention ordering/page behavior beyond limit, but the added semantics are substantive.

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 short sentences, front-loaded with the core purpose, followed by the traded-only constraint, the limit flag semantics, currency units, and the sibling hand-off. No filler or repetition of schema fields.

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 supplies exactly the row-level semantics an agent needs (traded-only listing, limit_up/limit_down flags, Rial pricing) and tells it how to drill down via siblings. A note on row ordering/pagination or the columns returned would make it fully complete.

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 schema already defines limit, market enum values, and sort_by semantics. The description's phrase 'ranked by gain, loss, volume, value or trade count' restates the sort_by enum without adding format or constraint detail, so 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 ('Top traded instruments of a market today') plus the ranking dimensions, so the agent knows this is a ranked leaderboard endpoint. Sibling tools like ts_indices and ts_price_history cover different resources, and the description's 'top traded instruments of a market' scope is clearly distinct from a single-symbol quote lookup.

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?

The description implies the discovery use case and explicitly routes follow-up work: 'Pass a row's `symbol` to ts_get_quote or ts_order_book.' It doesn't state when NOT to use this (e.g. use ts_price_history for a time series), but the context is clear enough for correct selection.

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

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

Annotations already establish readOnly, idempotent and non-destructive semantics, so the description earns credit for the operational details it adds: empty results outside trading hours, the meaning of a zero ask price (buy queue) and a zero bid price (sell queue), and that prices are denominated in Rial. These are exactly the quirks that would otherwise be misread by an agent.

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?

Three compact sentences with no filler: the primary capability first, then the empty-result caveat, then the edge case decoding and the currency unit. Slightly terse, but every sentence carries information.

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 one-parameter read tool with full schema coverage and no output schema, the description covers the return shape (five levels, with price, volume, order count), edge-case values and units. What is missing is how much the depth view differs from the quote tool and whether the response includes timestamps or ordering guarantees, but the essentials are present.

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% and the symbol parameter is fully documented with accepted forms (ticker, exact name such as 'فولاد', or numeric ins_code), so the schema carries the burden. The description adds no further meaning about the parameter, which is the baseline for a fully documented single-param schema.

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 the resource precisely: the five best bid/ask levels of one instrument, including the fields returned (price, volume, order count). It does not explicitly distinguish itself from the obvious sibling ts_get_quote, so an agent must infer that this is the depth view versus the top-of-book view.

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?

There is no explicit when-to-use or when-not-to-use guidance and no sibling is named as an alternative. The note that the book is empty outside trading hours is useful context about when the call returns nothing, but it is still only implied usage guidance.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, so the description focuses on what the data means. It adds real context beyond them: prices are in Rial, unadjusted for capital increases or dividends, and dates are Gregorian, and ordering is newest-first. It does not cover rate limits or failure behavior, but those are secondary for a read tool.

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?

Two short sentences with zero waste: returned fields and ordering first, then the units, adjustment, and calendar caveats. Every clause carries information an agent cannot get from the structured fields.

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 does the right job of enumerating the returned fields (open, high, low, close, volume, trades, value), their units, and ordering. It does not say what a response looks like structurally or what happens for an invalid or delisted symbol, which keeps it short of a 5.

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 both symbol and days are already documented in the schema, including the 15 KB reply size rationale for the 50-day cap. The description's 'latest trading days, newest first' restates the days semantics without adding syntax or format detail. Baseline 3 is appropriate.

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: returns daily OHLCV plus trades and value for one instrument. It implies single-instrument scope, which distinguishes it from ts_index_history and ts_market_movers, but never names an alternative explicitly.

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?

'for its latest trading days, newest first' implies a historical-series use case, but there is no explicit guidance on when to choose this over ts_get_quote (latest snapshot) or ts_index_history (indices). The choice 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.

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description still earns credit by adding meaning beyond them: the sign convention for net_real_volume, the newest-day-first ordering, and units (shares, Rial) — all things the annotations cannot convey.

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?

Three short sentences, front-loaded with the resource and segmentation, then the key interpretive rule, then ordering and units. Nothing is padding and every clause carries information.

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 does the required work: it explains the headline field's interpretation, ordering, and units. It stops short of describing the full result shape (e.g. the buyer/seller count fields it advertises), which is a minor gap for a read-only tool whose annotations are already clear.

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%, with both `days` (1-10, one upstream call per day) and `symbol` (ticker, exact name, or ins_code) fully documented in the schema. The description adds no parameter detail beyond that, 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?

The description states a specific verb ('buy and sell'), the exact measures (volume, value, buyer/seller counts) and the distinguishing segmentation (real vs legal traders, per day). No sibling tool competes with that scope, so an agent can tell instantly this is not ts_get_quote or ts_price_history.

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 implied by the scope statement rather than stated: an agent can infer this is for retail-vs-institutional flow analysis, but there is no explicit 'use this when' condition, no exclusions, and no mention of alternatives such as ts_price_history for raw price/volume.

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

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

Annotations already declare read-only, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds genuinely useful beyond-annotation context: what an empty list means and how to recover, plus the Persian spelling tolerance. It does not mention ranking/ordering of matches or pagination beyond the limit param.

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?

Three short, front-loaded blocks: what it finds, when to use it and what to do with the result, and what an empty result means. No filler sentences; each one carries distinct operational 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?

With no output schema, the description compensates by naming the returned identifiers used by downstream tools and by interpreting the empty-result case. For a 2-parameter read-only search, an agent has everything needed to call it and to handle the response.

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 baseline is 3; the description goes slightly beyond by framing `query` as either ticker or name and by naming the result fields (`symbol`, `ins_code`) an agent will need downstream. That output-mapping context is not in the input schema and is the main added value.

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 ('Find Tehran Stock Exchange instruments') and enumerates what can be found (shares, funds, rights, bonds) plus the matching keys (ticker or name). An agent can tell this apart from siblings like ts_get_quote, which need an already-resolved symbol.

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?

Explicitly says 'Use first when you only have a name' and directs the agent to pass the result's `symbol` or `ins_code` into the other ts_ tools, which is a clear routing rule to siblings. It also prescribes recovery behavior on an empty result ('retry with a shorter name or the other spelling').

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