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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real value beyond them: it discloses the three fields of the result (login state, expiry, pending step) and names the specific error codes that should route an agent here.

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, zero waste. The informational purpose is front-loaded and the routing rule follows it, in the order an agent needs them.

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 must convey what comes back, and it does so at the right granularity (logged-in state, expiry, pending login step). Combined with the error-code routing hint, an agent has everything needed to call it and act on 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?

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. Schema coverage is 100% and additionalProperties is false, leaving no ambiguity about invocation.

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 — it reports Thndr login state, session expiry, and the pending login step — which is distinct from every sibling (login_start, login_verify_code, logout, etc.) that performs or advances authentication rather than reporting it. An agent can identify this as the diagnostic tool without opening any 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 an explicit trigger condition: call it first when another tool returns NOT_AUTHENTICATED or SESSION_EXPIRED. That is concrete and actionable. It stops short of naming the alternative tools to call next (e.g. login_start vs login_import_session), so it is clear context rather than a full when/when-not rule.

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=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, so the safety profile is covered. The description adds non-obvious behavior the annotations cannot convey: app notification delivery and the market-dependent direction inference, including the US limitation.

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 tightly packed sentences with zero filler; the core action is front-loaded and the caveat is attached to the parameter it affects rather than tacked on at the end.

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 5-parameter mutation with no output schema and rich annotations, the description covers the operation, the tricky inference rule and the market exception. It does not mention what is returned on success, which is the only notable 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 100%, so the baseline is 3, but the description genuinely extends `direction` semantics beyond the field text ('derived from the current price if omitted') by explaining the US case where inference is impossible. Other parameters (market, price, symbol, frequency) are left to the 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 gives a specific verb+resource plus the triggering behavior: 'Creates a price alert that notifies the user in the Thndr app when the instrument crosses `price`.' This clearly separates it from get_alerts/get_alert/update_alert/delete_alert by operation type, though it never names those siblings 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?

It supplies a concrete conditional rule for a non-obvious parameter: direction is inferred from current price unless given, and must be supplied explicitly in the US because no whole-market snapshot exists there. That is real when-to-do-what guidance, though it does not discuss alternatives or prerequisites like auth.

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=false, idempotentHint=false, and openWorldHint=true, so the agent knows this is a non-idempotent write with external effects. The description adds that it returns the new id, which helps with follow-up calls, but doesn't state failure modes, naming constraints (beyond schema maxLength), or the effect of duplicate names.

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: first states the action and optional prefill, second states the return and where to read next. No filler, front-loaded with the core operation.

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 3-parameter creation tool with no output schema, the description covers purpose, optional parameters, return value, and next step. Missing only minor behavioral details like duplicate-name handling or default market behavior, which are partially covered by schema defaults.

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 only 33%, so the description must compensate. It clarifies that 'symbols' accepts either ticker symbols or Thndr asset ids, adding meaning beyond the schema's brief item description. The 'name' and 'market' parameters are adequately covered by the schema. The description doesn't explicitly explain the 'market' enum values, but the schema does.

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 (Creates) and resource (watchlist) with scope detail about what it can be pre-filled with (tickers or asset ids). Clearly distinguishes from siblings like get_watchlist and edit_watchlist by naming one as the read counterpart.

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 names get_watchlist as the read alternative and implies this is the creation path. Doesn't cover when not to use it (e.g., if a watchlist already exists) or prerequisites, but the routing guidance is 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?

The annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false, and openWorldHint=true, so the safety profile is fully covered by structured data. The description adds nothing on top of that — no note about permanence, whether the alert can be recovered, or required authorization — so it earns no credit 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?

One short, front-loaded sentence with no filler or redundancy — there is nothing wasted. Its brevity is appropriate, even if the content is thin; the problem is omission, not verbosity.

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 destructive mutation with a required identifier, 0% schema description coverage, and no output schema, the definition is too sparse. An agent cannot learn from it where the id comes from or whether the deletion is permanent, even though the annotations do cover the destructive/idempotent character of the call.

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 0% for the single required parameter 'id', so the description carries the burden of explaining it. The phrase 'a price alert' only loosely implies that an alert identifier is needed, but it never states what the id is, where to obtain it (e.g., from get_alerts), or its format.

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 sentence restates the tool name and title almost verbatim ('delete_alert' / 'Delete price alert'), adding no scope, target, or qualifier. It does convey a clear verb+resource, but it is a tautology rather than an informative purpose statement, and it does nothing to distinguish itself from sibling deletes such as delete_watchlist.

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 indication of when to use this tool versus update_alert, get_alert, or delete_watchlist, and no precondition such as confirming the alert exists or warning that deletion is irreversible. No guidance is offered at all.

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 destructiveHint=true, idempotentHint=true, readOnlyHint=false, so the safety profile is largely covered. The description adds the useful 'permanently' qualifier confirming irreversibility, but says nothing about cascade effects (e.g. alerts inside the watchlist) or recovery options.

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?

One short sentence with zero filler, front-loaded with the verb and resource. Nothing redundant and nothing that wastes the agent's attention.

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 low-complexity one-parameter destructive tool the description is nearly adequate, and annotations carry the safety semantics. However, it omits the identifier requirement and any impact/recovery context expected of an irreversible delete with no output schema.

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 0% and the single required 'id' parameter is completely undocumented in both schema and description. The description gives no hint about what identifier to supply or its format, so it fails to compensate for the coverage gap.

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 ('Deletes a watchlist') and adds the permanence qualifier. It is clearly distinguishable from create_watchlist/edit_watchlist by name, though the description itself never names a sibling to sharpen the contrast.

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 guidance, no mention of alternatives such as edit_watchlist, and no statement of prerequisites or confirmation steps. The word 'permanently' hints at caution but does not route the agent.

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=false, idempotentHint=true and destructiveHint=false, so safety is covered. The description adds genuine context the annotations cannot: that add/remove/rename can be batched into a single call and that the tool reports back what changed, which matters because there is 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?

Two short sentences with no filler: the first front-loads the full set of operations, the second covers return behavior and the read alternative. Every clause earns its place.

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 5-parameter mutation tool with 20% schema coverage and no output schema, the description leaves real gaps: the required id, the role of market in resolving ticker symbols, and the 100-item cap on add/remove are all unmentioned. It does cover the return shape adequately.

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 only 20%, so the description has to carry more weight. It maps its prose onto the name, add and remove parameters, but leaves the required 'id' undocumented and never explains how 'market' governs ticker resolution for add/remove.

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 gives a concrete verb plus resource (rename a watchlist, add/remove instruments) and spells out the three sub-operations an 'edit' can perform, which is more than the title alone conveys. It also names get_watchlist as the read counterpart, though it stays silent about the adjacent create_watchlist/delete_watchlist siblings.

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 points the agent at get_watchlist for reading the resulting list, which is a usable post-call routing hint. However there is no guidance on when to edit vs. create or delete a watchlist, nor on prerequisites such as needing a valid watchlist id first.

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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower, and the description still adds real behavioral value: result ordering (newest first), the 2000-entry scan cap, and the truncated=true signal when the cap is hit. It omits how market scoping interacts with the range and whether auth/session state is required, so it is strong but not exhaustive.

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, zero filler: the first defines what the ledger contains, the second front-loads the paging and truncation contract. Everything an agent needs to avoid misreading the range parameters is stated compactly.

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 sensibly describes the return shape at a high level (ordered entries, truncation flag) and explains the range/pagination tradeoff for 7 all-optional parameters. The remaining gap is entry-level content and how market/category interact with the range, which is minor rather than blocking.

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 57%, and the description reinforces the from/to vs period exclusivity (already stated in the schema) plus the paging behavior tied to page/pageSize. It adds nothing about category, market, or the per-parameter defaults, so it does not compensate for the roughly half of parameters left undocumented in both places.

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 concrete resource ('Cash ledger') and enumerates exactly which entry types appear in it (deposits, withdrawals, order settlements, dividends, fees, transfers), which separates it reasonably well from siblings like get_account_orders or get_account_summary. It stops short of explicitly saying which sibling to use for order-level or summary-level questions, so it is clear but not fully differentiated.

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 only implied through the paging note: no date range returns one page, with from/to or period you get the full range. There is no explicit statement of when to prefer this tool over get_account_orders, get_realized_returns, or get_account_summary, nor any prerequisites (e.g., authenticated account context) spelled out.

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=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered. The description's 'this server cannot place, change or cancel orders' largely restates that, and it omits genuinely useful behavior such as how limit/cursor pagination behaves or whether results are scoped to the authenticated account.

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 with the purpose and field list front-loaded and the read-only constraint last. Nothing is padded, though the parenthetical status list duplicates schema enum values rather than earning new 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 six optional parameters, no output schema, and a cursor-based pagination scheme, the description is thin on how to page through results and what the response envelope looks like. It does name the returned order fields, which partially covers the missing output schema, but pagination and default scoping remain undocumented.

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 50%: cursor, market and symbol carry descriptions, while limit, status and oldestFirst do not. The description restates the status enum values already present in the schema rather than adding meaning (e.g. what 'closed' vs 'completed' means), so it does not compensate for the coverage gap. 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?

Names a specific resource (order history and status) and enumerates the returned fields (side, type, quantity, filled quantity, price, validity, brackets), so the agent knows exactly what this returns. It does not explicitly differentiate from near-neighbours like get_closed_trades or get_account_activity, which is the only thing keeping it from a 5.

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 rather than stated: an agent can infer this is the tool for viewing orders, and the read-only sentence clarifies scope. But there is no explicit when-to-use guidance and no routing to alternatives such as get_closed_trades for filled/closed activity, leaving the agent to guess among similar siblings.

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 covered. The description adds nothing behavioral beyond that — it does not say whether results are scoped to the authenticated account, how the market parameter changes behavior, or whether sorting/ordering applies. With annotations carrying the safety burden, this is a thin addition.

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?

A single front-loaded sentence listing the returned fields with zero filler. It is appropriately sized, though the fragmentary noun-phrase structure means it never states the action being performed.

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, listing the returned fields is genuinely useful and is the description's main contribution. But for a multi-market portfolio tool with sorting and ordering options, the description omits which account the positions belong to, how 'market' scopes the result, and how the three parameters interact.

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 only 33% (only 'market' is documented in the schema; 'order' and 'sortBy' rely on enum names alone). The description mentions no parameters at all, so it does not compensate for the coverage gap, even though the enum values are largely self-explanatory.

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 enumerates the data returned (quantity, average cost, market price, unrealized P/L, weight, allocation), which lets an agent infer this lists account holdings. However it is a bare noun phrase with no verb and no scope statement, so it does not clearly distinguish itself from siblings like get_position, get_portfolio_allocation, or get_account_summary.

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 when-to-use guidance, no mention of alternatives (e.g. get_position for a single holding, get_portfolio_allocation for allocation-only views), and no stated prerequisites. The agent must infer the context entirely from the name.

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, and open-world behavior, so the description's main added value is explaining return semantics, e.g., that blocked cash is reserved by open buy orders. This is useful context beyond annotations, though it does not cover authentication needs or data freshness.

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 a single front-loaded sentence that efficiently lists the key values without redundant wording. Every phrase contributes to understanding what the tool returns.

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 carries the burden of explaining return values, and it does so by enumerating the fields. It omits output formatting details (e.g., currency, number types), but annotations and the parameter schema cover safety and input semantics adequately.

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?

The schema has 100% description coverage for the single market parameter, including enum values and defaults. The description adds no additional parameter meaning, so the baseline score 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 clearly identifies the resource as the Thndr account summary and enumerates the specific financial values returned (buying power, blocked cash, unsettled cash, etc.). It does not explicitly distinguish itself from siblings like get_account_positions or get_portfolio_allocation, but the scope is specific enough for an agent to recognize it as a summary tool.

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 provides no guidance on when to use this tool versus alternatives such as get_account_positions, get_portfolio_allocation, or get_trading_metrics. It only lists the returned fields, leaving the agent to infer the appropriate context.

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 the full safety profile (readOnly, idempotent, openWorld, non-destructive), so the description is not required to carry that burden. However, it adds nothing behavioral beyond that — no indication of error behavior for an unknown id, scoping, or return shape.

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?

A single fragment with zero waste and the key information front-loaded, but it leans toward under-specification rather than true conciseness given the tool's context.

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?

There is no output schema, so the description could have signaled what a price alert record contains. For a simple single-record retrieval with strong annotations, the terse description is minimally adequate but leaves return-shape ambiguity.

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 50%: the market enum is fully documented in the schema, while id has no description but is self-evident. The phrase 'by id' confirms id is the lookup key, adding only marginal meaning beyond the 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?

States a specific verb (get) and resource (price alert) with a scope qualifier (one, by id), which distinguishes it from the sibling get_alerts list tool. It is clear but does not explicitly name the sibling or contrast behavior.

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?

No when-to-use guidance, no mention of alternatives like get_alerts, and no prerequisites. The agent must infer from the name that this is the singular lookup versus the list.

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, and destructiveHint=false, so the safety profile is covered structurally. The description adds one genuine behavioral fact beyond that: results are paged. It does not describe page size limits, sorting, or what happens on out-of-range pages.

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 the resource front-loaded and no filler. 'Paged.' as a fragment is terse but functional; nothing wastes space.

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 and annotations covering safety, the remaining burden is explaining the two undocumented paging parameters and the relationship to the singular get_alert sibling; neither is addressed. Adequate but with clear gaps for a 4-parameter tool.

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 50%: market and symbol are documented in the schema, while page and pageCount are undocumented anywhere. 'Optionally only for one instrument' loosely maps to symbol and 'Paged' loosely to the paging params, but no defaults, ranges, or format details are added beyond the 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?

Identifies a specific resource (price alerts of the account) with a scope qualifier (optionally one instrument) and a paging note. It is clearly distinguishable from create_alert/update_alert/delete_alert, but it does not distinguish itself from the singular sibling get_alert, which shares a very similar name.

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 phrase 'optionally only for one instrument' implies the filter condition for narrowing results, but there is no explicit when-to-use guidance and no mention of how this differs from get_alert (singular), the closest sibling. Usage is only implied.

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 and destructiveHint=false, so the safety profile is covered. The description adds content semantics (round trips, net P/L, holding period) but says nothing about timezone handling, pagination behavior, or how period interacts with from/to beyond what the schema states.

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?

A single dense fragment that front-loads the resource and enumerates its fields with zero filler. Nothing could be removed without losing 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 field enumeration partially compensates by describing the return payload. However, a 7-parameter read tool with preset ranges and pagination would benefit from guidance on combining period with from/to and on default market scope, none of which is 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 71%, with the from/to/period/market/symbol params well documented in the schema itself, while page/limit are undocumented but self-evident given defaults and bounds. The description contributes no filtering syntax or edge-case detail (e.g. period vs from/to mutual exclusion), so it neither compensates for the gap nor adds meaning beyond the 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 (a trading journal of round trips) and enumerates the payload fields (entry/exit dates and prices, volume, net P/L, holding period), so an agent knows exactly what it returns. It stops short of an explicit verb and does not contrast itself with the closely related siblings get_recent_trades or get_realized_returns, which would be needed for a 5.

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 guidance on when to call this tool versus the many sibling reads such as get_recent_trades, get_realized_returns or get_sell_journal. Prerequisites, scope (e.g. whether it covers all markets by default), and exclusions are entirely absent.

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 covered. The description adds real context beyond that: newest-first ordering, the two dividend types, the exact fields returned, and that an empty list means no records exist rather than an error. It doesn't discuss rate limits or pagination interactions, so not 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?

A single dense sentence with the resource and returned fields front-loaded, followed by the empty-list caveat. Every clause carries information, though the colon-list construction is slightly packed and could be split for readability.

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 correctly compensates by enumerating the returned fields and their semantics, and annotations cover the safety profile. Pagination is handled by the schema, so the remaining gap is minor: no note on whether historical coverage differs per market or symbol type.

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 page, limit, market and symbol all documented inline (including enum meanings and defaults). The description adds nothing syntactic about these parameters, so the baseline 3 applies; 'Any market' loosely gestures at the market param but adds no new meaning.

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 (an instrument's dividends) and enumerates the returned fields (cash/stock, record date, payment dates, currency, status), so the agent knows exactly what this returns. It does not explicitly contrast itself with siblings such as get_financials or get_price_performance, which keeps it just short of a 5.

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 when-to-use or when-not-to-use guidance and no named alternative, even though sibling tools like get_financials plausibly overlap. The 'Any market' and 'empty list' notes are behavioral facts rather than routing guidance, leaving usage 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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds the notable behavioral fact that results carry Thndr's own source descriptions and that both headline readings and series points come back together, but it says nothing about rate limits, refresh cadence, or how much data volume to expect.

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?

A single sentence that front-loads the critical scoping constraint ('Egypt only') before the enumeration. The nested list of indicators is dense and slightly run-on, but every clause names actual return content, so little is wasted.

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 carries the burden of describing returns and does so thoroughly by enumerating the headline metrics and series. The only gap is that it never states the effect of the `points` parameter on payload size, though the schema covers that.

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% and the single `points` parameter is fully documented in the schema (default 12, min 1, max 500). The description's phrase 'the latest points of the ... series' loosely corroborates the parameter's meaning but adds no format, units, or edge-case detail 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?

Names a specific resource (Egypt macroeconomic data) and enumerates the exact readings returned: inflation, CBE deposit/lending rates, T-bill yield, unemployment, GDP, plus series history. The 'Egypt only' scope and the Thndr-specific framing make it unmistakable against every sibling, none of which touch macro data.

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 'Egypt only' scoping constraint tells the agent the applicability boundary, which is real guidance. However, there is no explicit when-to-use vs when-not framing and no mention of alternatives (there are none among siblings), so usage is only implied rather than directed.

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, so the burden is lighter. The description adds real context beyond them: that metrics excludes valuation multiples, that compareToSector always covers every ThndrX-compared metric, and what the comparison returns (median/min/max, percentile). It does not state cost/rate-limit behavior, but for a read tool this is solid.

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 dense sentences, front-loaded with scope and returned content, then the compareToSector behavior. No filler and every clause carries information an agent needs.

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 and six parameters on a fairly complex data tool, the description covers what is returned and how the sector comparison behaves, which is the key missing structured context. The unresolved 'Egypt only' vs market-enum mismatch is the main completeness 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 100%, so a baseline of 3 is warranted, but the description adds meaning the schema lacks: the dependency that 'metrics' does not affect the sector comparison and that compareToSector is the route to valuation multiples. This clarifies the interaction between two parameters rather than restating field docs.

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 ('financial statements and ratios of a listed company from Thndr') and enumerates the statement families returned, which distinguishes it from price/peer tools. However, the leading scope claim 'Egypt only' is misleading: the market parameter accepts 'us', 'uae' and 'simulator', so an agent reading only the description would wrongly exclude valid markets.

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 in-parameter routing (use compareToSector for P/E, P/B, P/S, PEG, EV/EBITDA since Thndr serves no valuation multiples), which is genuinely helpful. But it never says when to prefer this over siblings like get_peers, get_price_performance or get_instrument_details, so cross-tool selection 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 read-only, idempotent, open-world, non-destructive behavior, so the safety profile is covered. The description adds genuine behavioral context beyond that: the dual-mode semantics, the sort ordering driven by `sortBy`, and the data limitation that Thndr provides no index weights. It does not cover pagination/limit behavior or how an unrecognized index is handled.

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-loads the scope constraint and then the two modes, with dense field enumerations rather than prose. Every sentence carries information; the only mild drag is the parenthetical index list, which is useful but long.

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 correctly compensates by enumerating the fields returned in each mode (level/change%/member count vs sector/last/change/value/volume/market cap). It also flags the 'Egypt only' limitation. It omits return pagination and the interaction between `limit`/`sortBy`/`order` defaults beyond what the schema states.

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 60%, so the description must carry some weight — and it does: it explains the semantics of `index` (mode switch, with the EGX70→EGX70-EWI alias) and that results are sorted by `sortBy`. `limit`, `order`, and `market` details are left largely to the schema, which is acceptable at this coverage level.

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 (index constituents) and precisely defines two distinct behaviors keyed on whether `index` is supplied, including the returned fields for each mode. It also scopes the tool geographically ('Egypt only') and names concrete indices (EGX30, EGX70 EWI, Shariah), making it easy to separate from siblings like get_markets or search_instruments.

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 tells the agent how to trigger each mode: omit `index` to list indices, supply `index` to get member instruments. It adds the caveat that index weights are unavailable so the agent doesn't promise them. It stops short of naming an alternative tool for the related task (e.g. get_markets for broad market data).

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, open-world, non-destructive, so safety is covered. The description adds a genuine behavioral nuance beyond them: the market-dependent `indices` field is populated for Egypt and null elsewhere, which shapes how an agent interprets 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 dense sentences, front-loaded with the general (all-markets) behavior before the market-specific exception. Every clause carries information; no filler.

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 correctly compensates by enumerating the returned fields, and annotations carry the safety profile. It is nearly complete, though it omits any note on auth requirements or error behavior for unknown symbols.

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 `market` enum is fully documented in the schema, so the baseline of 3 applies. The 'Egypt only … null elsewhere' note adds market-specific meaning, but it describes output behavior rather than clarifying the parameter itself.

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 precise verb+resource ('company profile and listing details for one instrument') and enumerates the returned fields, making the data scope obvious. The 'for one instrument' framing cleanly separates it from search_instruments, which discovers symbols rather than describing one.

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 single-instrument framing implies a lookup-by-symbol use case versus search, but the description never explicitly says when to reach for this tool versus search_instruments, get_peers, or get_financials. Usage is inferable but not stated.

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 covered. The description adds real value by describing the return shape (levels aggregated by price with order counts, plus the spread) and a coverage restriction ('Egypt only'). It omits any refresh/rate-limit behavior and the restriction conflicts with the schema's market enum, so it is not a clean disclosure.

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?

A single tight sentence with no padding, and the scope constraint is front-loaded before the payload description. Only the ambiguous 'Egypt only' prefix keeps it from being maximally efficient.

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?

There is no output schema, so the description carries the return-value burden; it does describe the two return components (aggregated book and spread), which is helpful. But it never explains what 'levels' does to the output size, nor any auth or market-availability rules, leaving gaps for a 3-parameter tool.

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 67%: symbol and market are documented, but the 'levels' parameter (default 10, max 50) has no description anywhere, and the description's 'aggregated by price level' phrasing does not explain that levels controls depth count. Worse, 'Egypt only' actively contradicts the market enum that allows 'us', 'uae' and 'simulator', giving the agent misleading guidance about the market 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?

States a specific resource and its contents: an order book with bids/asks aggregated by price level plus the bid/ask spread. That distinguishes it from siblings like get_price_snapshot and get_recent_trades. The leading 'Egypt only' qualifier, however, sits in tension with the schema's four-value market enum, so the scope claim is less clean than it looks.

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?

No when-to-use guidance and no routing to alternatives. The description never says how this differs from get_price_snapshot (last price), get_recent_trades (trade tape) or get_market_status, so the agent must infer which depth-adjacent tool to call.

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, open-world behavior, so the safety profile is covered. The description adds real behavioral context beyond that: only Egypt and US actually return data despite the enum's uae/simulator values, and US lists may contain instruments flagged tradable: false — a caveat an agent needs before acting on 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?

Three short sentences with no filler; the core purpose leads, and the scope caveats (Egypt/US only, tradable: false) follow. Every clause carries information an agent needs.

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 usefully characterizes the return shape (instruments ranked by return with price and today's change) and the tradable flag. It stops short of clarifying whether type=both yields two separate lists or how the limit interacts with that, which is a minor remaining gap for a 4-parameter read tool.

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 and the schema already documents all four parameters and their enums. The description still adds value by confirming the ranking periods, restating the Egypt/US restriction that constrains the market enum, and describing what each returned instrument carries (price and today's change).

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 (Thndr's top gainers/losers), the ranking basis (return), the supported periods, and the geographic scope. An agent can tell this apart from neighbors like screen_market, get_trending, or get_price_performance without opening any 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?

Usage is only implied: this is the tool for ranked top-mover lists, and the type/period parameters hint at how to narrow it. There is no explicit statement of when to prefer this over screen_market or get_trending, and no exclusions or prerequisites are given.

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 the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower, and the description adds real content disclosure: restrictions, per-market exchange/currency/time zone, and which thndr-mcp features work in each market. It does not mention auth requirements or caching/rate behavior, but it substantially exceeds the annotation coverage.

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?

It is front-loaded with what the tool returns, then closes with the actionable usage sentence. The parenthetical examples are dense but each one earns its place by telling the agent which features are region-restricted; the only cost is a slightly packed first 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?

There is no output schema, so the description must carry the return-value burden, and it does: markets, default, restrictions, exchange, currency, time zone, and feature availability are all enumerated. An agent can call this and know what it will receive without further documentation.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a 0-param tool applies. Nothing in the description misrepresents or omits parameter behavior.

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 (Thndr markets available to the account) and enumerates exactly what is returned: the set of markets, the default, restrictions, and per-market exchange/currency/time zone. It is immediately distinguishable from data-fetching siblings like get_market_status or get_market_movers because it describes account-scoped metadata about where those tools apply.

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 a clear call-to-action ("Call it to learn where a tool applies") and even supplies concrete routing examples — order book, candles and financials are Egypt-only; movers are Egypt and US. That is strong context for choosing region-scoped tools, but no explicit when-not-to-use or named alternative is stated.

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 safety profile is covered. The description adds genuinely useful context beyond that: which markets are covered, which index symbols are surfaced per market, and the regular-session windows with explicit timezones (Africa/Cairo, America/New_York). It stops short of holiday/exception handling.

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 primary output (open/closed status) before expanding into session times and index lists, and the second sentence isolates the trading-hours reference data. Dense but every clause carries information; the ellipses in the index examples are the only slightly loose element.

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 carries the return-value burden and largely does so: status, session times, and benchmark symbols. Timezones are given for regular sessions, which is the key ambiguity. It omits holiday/half-day handling and what the simulator returns, but that is a minor gap for a status-lookup tool.

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 enum values are already documented, so the baseline is 3. The description adds real meaning on top by mapping each market to the benchmarks returned (Egypt: EGX30/EGX70; US: SPY/QQQ/DIA; UAE: FADGI) and by reinforcing the "not the simulator" qualifier that the schema's simulator entry does not convey.

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 concrete verb+resource (report whether a market is open, session open/close times, and headline indices/benchmarks) and scopes it to three named markets. The parenthetical "not the simulator" actively distinguishes it from the get_markets sibling, so an agent can route 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?

Gives clear context for when to call it (Egypt/US/UAE market state and benchmarks) and an explicit exclusion ("not the simulator"), but never names the alternative tool an agent should use for the simulator or for broader market listings. The condition that selects a sibling is implied rather than stated.

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?

Goes well beyond the annotations by disclosing pagination (25 per page, newest first), de-duplication of repeated filings, `limit` keeping the first N, and content truncation to `contentChars` (default 500) with EGX disclosures being PDFs. These operational traits are exactly the kind of context annotations cannot carry.

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?

Dense but front-loaded, leading with the core purpose before the conditional branches. Some sentences pack multiple clauses (market fallbacks, truncation, PDFs), slightly straining single-pass readability, but every sentence carries distinct 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 partially carries the return burden by naming the `link` field and truncation behavior, and all 6 params are covered. It stops short of describing the article record structure (title, date, source), so an agent knows how to paginate and fetch text but not the full shape of each item.

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. The description adds real meaning on top: it clarifies the `symbol`-vs-`market` interaction, that `limit` keeps the first N, and that truncated content should be retrieved via `link`, which the schema fields do not convey on their own.

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 resource (news and exchange disclosures from Thndr's feed) with ordering (newest first) and scope (one instrument, or market-wide). It clearly distinguishes the symbol-filtered path from the market-wide path, which no sibling tool offers.

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 explains conditional behavior: with `symbol` you get one instrument's news; without it, `market: "us"` yields US news and any other market yields the mixed EGX+US feed. It also flags the UAE no-results edge case and tells the agent to follow `link` for full text.

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, and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond that: the newest-first ordering and what kinds of events appear. It says nothing about pagination behavior or how unread state is surfaced, which matters for a paginated list.

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?

One compact sentence, front-loaded with the resource and its content. The parenthetical example list is slightly long but conveys real value in identifying what appears here.

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 need not explain return values, and annotations cover the safety profile. However, for a clearly paginated, filterable list tool it leaves the three input parameters entirely unexplained, which is the main remaining 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 description coverage is 0% for three parameters (page, pageCount, unreadOnly), and the description does not compensate at all. It never explains the paging model or what unreadOnly does, so an agent must guess that unreadOnly filters to unread items and that page/pageCount paginate.

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 resource (in-app notifications) with concrete content examples (order fills, rejections, price alerts) and a default ordering (newest first). This separates it from sibling get_alerts and mark_notifications_read implicitly, though it never names them outright.

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?

No statement of when to call this versus mark_notifications_read (the write counterpart) or get_alerts (the alert-configuration tool). Usage must be inferred entirely from the tool name and resource description.

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, open-world, and non-destructive, so the safety bar is met. The description goes beyond them by disclosing market-dependent output behavior: Egypt adds sameSector instruments plus traded value, market cap, P/E and dividend yield, while elsewhere sameSector is empty and those fields are null. This is genuinely useful behavioral context; only the absence of any return-shape detail beyond a field list keeps it from 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?

A single dense sentence, front-loaded with the "All markets" scope so the universal behavior is read first. Every clause carries information and none is redundant, though the semicolon-chained structure is slightly run-on.

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 carries the job of explaining returns and partially does so (last price, change %, and the Egypt-only field set). Annotations cover the safety profile and the schema covers all parameters, so nothing critical is missing, though a bit more on the non-Egypt return shape would complete it.

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 fully documents symbol, market, and limit. The description implies that the `market` parameter materially changes the returned fields (Egypt vs. elsewhere), which adds some meaning beyond the enum, but it does not explain limit, symbol formats, or market-specific syntax beyond what the schema states. 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?

The description states a specific verb+resource: it returns Thndr's "similar stocks" for a single stock, with concrete fields (last price, change %). It is clearly distinguishable from generic sibling tools like get_market_movers or search_instruments. It stops short of naming a sibling to route against, so it lands at 4 rather than 5.

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 phrase "for one stock" implies the input context, but there is no explicit when-to-use/when-not guidance and no reference to alternative siblings such as get_market_movers or get_index_constituents. An agent must infer usage from the purpose statement alone.

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=true, idempotent=true, openWorld=true, and non-destructive, so the safety profile is covered. The description adds useful behavioral detail about data provenance and bucket semantics, which is genuinely beyond the annotations. However, it omits the US/UAE truncation trigger ('at most 30 holdings, heaviest first') as a caveat only in passing and says nothing about empty-portfolio behavior or response shape.

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 single dense sentence is packed with parenthetical caveats and overlapping index-membership trivia ('they overlap and do not sum to 100%') that cost reading effort disproportionate to the value delivered. Front-loaded subject is fine, but the mid-clause clutter hurts scannability.

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?

Covers market-specific data sources and bucketing rules, which is meaningful context for a read-only aggregation tool. But with no output schema and no response-shape hint, an agent still cannot predict the return structure well enough to chain results reliably.

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 enum parameter is fully documented in the schema. The description implies market-specific output differences but adds no syntax or format detail beyond what the schema's enum description already provides. Baseline 3 is correct when the schema does the heavy lifting.

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 (allocation of a portfolio's holdings by asset class and sector) and clearly differentiates its output shape from siblings like get_account_positions or get_portfolio_performance. It is dense but an agent can tell what it returns 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?

The description implies when the output differs by market (Egypt vs US/UAE/simulator behavior) but never states when to prefer this tool over siblings like get_portfolio_performance or get_account_summary. The market-dependent behavior hints at usage context but no alternatives or exclusions are named.

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 openWorld. The description adds genuine behavioral context beyond that: the source is 'Thndr's returns chart', granularity varies (daily/weekly), and periods may be 'only partly covered' — a caveat an agent would otherwise not know. It stops short of explaining auth or error behavior.

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?

A single front-loaded sentence that leads with the resource and periods before enumerating return fields. Dense but every clause describes a distinct returned value; no filler or repetition of the name/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?

With no output schema, the description usefully compensates by enumerating the returned fields and caveats. For a one-optional-parameter read tool whose safety profile is covered by annotations, this is close to sufficient; only the auth/account prerequisite and cross-tool routing are absent.

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?

One optional parameter with 100% schema description coverage — the enum values and market mappings are already documented in the schema, so the baseline is 3. The description adds nothing about the market parameter's effect on returned data.

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?

Names a specific resource (portfolio performance) with concrete scope: a fixed set of periods (1D–2Y) and an enumerated set of returned metrics. This distinguishes it from data-returning siblings like get_price_performance and get_realized_returns, though it 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?

The description states what comes back but never says when to choose this tool over get_price_performance, get_portfolio_allocation, or get_realized_returns, nor does it state prerequisites (e.g., authenticated account with positions). No exclusions or context cues are given.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavior beyond them: a missing holding returns held=false rather than erroring, and includeSellable=true expands the response with sellable share counts split across T0/T1/T+2 settlement cycles. It does not state error behavior for an invalid symbol, 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?

Two compact sentences, front-loaded with the primary return semantics and the optional flag's effect. No filler, no 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?

With no output schema, the description carries return-value burden and does so for the main cases (holding present, held=false, sellable breakdown). It leaves gaps on failure modes for unknown symbols and on how market selection interacts with symbol lookup.

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 67%: market and symbol are documented in the schema, but includeSellable has no schema description, and the description compensates by explaining exactly what turning it on returns (sellable quantity per settlement cycle). This adds meaning the schema alone does not convey.

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 resource and scope: the holding in ONE instrument, with the held=false outcome named. That single-instrument scope implicitly separates it from get_account_positions, but the description never names that sibling, so differentiation is inferred rather than stated.

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 'one instrument' (versus the portfolio-wide get_account_positions), but there is no explicit when-to-use, when-not, or named alternative. The includeSellable=true trigger is the only conditional guidance offered.

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 cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial behavior: the per-market return contract (`kind: "candles"` vs `kind: "closes"` with a `{time, close}` point shape), the server-chosen close spacing (hourly/daily/weekly), and a hard ~5-year history cap. This is exactly the kind of non-obvious detail annotations cannot express.

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 market scope, then the two return contracts, then the windowing rule and the limit. Dense and information-rich with little waste, though the parenthetical shape notation makes it slightly hard to scan.

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 steps up and documents the return structure well (candle vs close payloads, point shape, spacing policy) plus the retention limit. The only missing piece is guidance on choosing this over sibling quote/performance tools.

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 genuinely adds meaning: `bars` is the most-recent-N form with default 100, and it clarifies that `bars` and `from`/`to` are mutually exclusive alternatives rather than combinable. It also reinforces the market-dependent effect of `resolution`.

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 (historical price data) and immediately qualifies the return shape per market (OHLCV candles for Egypt, closes elsewhere). An agent can tell this apart from get_price_snapshot or get_price_performance from the description alone.

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 explains the two windowing modes (`bars` vs `from`/`to`) and the ~5-year history limit, which implies usage, but never names or contrasts a sibling such as get_price_snapshot (current quote) or get_price_performance. The agent must infer when this tool is preferable to alternatives.

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 cover safety (readOnly, idempotent, non-destructive), so the description's added value is the disclosure that the underlying data differs by market — daily candles for Egypt, mixed daily/weekly closes elsewhere, and that the 52-week range is computed from closes rather than intraday highs/lows. That is a real behavioral caveat affecting interpretation. It does not mention rate limits, auth, or latency.

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 resource and the full metric list before the per-market data-source caveats. Dense but every clause carries information; the em-dash-heavy second sentence is slightly run-on but not padded.

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?

There is no output schema, so the description must describe returns, and it does so thoroughly (all return windows, three volatility horizons, range, drawdown). Combined with annotations and a fully documented 2-param schema, an agent has enough to call it correctly; only edge cases (insufficient history, units) are unaddressed.

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 enum already lists the four markets, so baseline is 3. The description adds meaning beyond the schema by tying each market to a different data source and granularity, which materially changes how the same `market` value affects the output.

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 ('trailing performance of one instrument') and enumerates exactly what is returned (returns windows, volatility, 52-week high/low, max drawdown, Thndr 1Y return). This clearly separates it from siblings like get_price_snapshot, get_price_history and the account-level get_portfolio_performance.

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 explains data provenance per market ('Egypt: from daily candles', 'US, UAE and others: from Thndr's closing prices') and points to `history` and `method`, which implies when results are granular vs coarse. However, it never states when to pick this tool over get_price_snapshot or get_price_history, so usage is only implied.

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 cover readOnly, idempotent, openWorld and non-destructive, so the safety profile is free. The description adds real behavioral value beyond that: it discloses which fields are populated per market and explicitly warns that non-Egyptian instruments return null for most fields, which prevents an agent from misreading sparse responses. It omits any note on rate limits or latency.

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 core capability ('All markets: current quote for up to 50 instruments'), then per-market field detail. The field enumerations are long but each one conveys concrete return-shape information rather than filler.

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 correctly carries the return-value burden and does so in detail: field sets per market, null behavior for US/UAE, and cross-market id mixing. It is nearly complete for a snapshot tool, lacking only response-size or timing caveats.

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 enum values and the symbol/UUID format are already documented in the schema. The description's note that asset ids of different markets may be mixed largely restates the schema's own 'they may be mixed' wording, adding little new parameter meaning.

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: 'current quote' for up to 50 instruments across markets. This implicitly separates it from get_price_history (historical) and get_instrument_details (metadata), but it never names those siblings or explicitly draws the boundary, so it stops short of a 5.

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 establishes scope (all markets, up to 50 symbols, ids may be mixed) but gives no explicit when-to-use/when-not guidance and never routes the agent to an alternative such as get_price_history or get_instrument_details. Usage is only implied by the content.

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 and non-destructive, so safety is covered. The description adds meaningful behavioral context by spelling out how 'realized returns' is computed (account value minus net deposits, unrealized gains included), but says nothing about auth requirements, rate limits, or the response format beyond that definition.

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?

A single sentence that front-loads the primary content (the cumulative return figure) and then the time series. The parenthetical definition earns its place, though the sentence is dense with parentheticals and could be tightened slightly.

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?

No output schema exists, so the description carries the burden of describing return content, and it does so adequately (cumulative return plus a series of account value, net deposits and returns). Combined with annotations that cover the read-only/idempotent safety profile, an agent has enough to call it correctly, though return shape and units are not detailed.

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 only 50%: the market enum is documented in the schema while the interval enum is not. The description restates the interval choices ('1M, 6M, 1Y or 2Y') but adds no format or default detail, and it does not explain the market values, so it only marginally compensates for the coverage gap. Baseline 3 for a mostly self-explanatory enum 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 states a specific resource (cumulative realized returns plus a time series) and even defines the metric's formula (account value minus net deposits, unrealized gains included). It is clear what the tool produces, but it never names or contrasts with siblings like get_portfolio_performance or get_account_summary, so sibling differentiation is left to inference.

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 when-to-use guidance, no prerequisites, and no named alternative. An agent must guess whether to call this or get_portfolio_performance/get_account_activity based on the metric name alone.

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, so safety is covered. The description adds pagination direction and a market restriction, but the 'Egypt only' claim conflicts with the schema's market enum (egypt/us/uae/simulator), which makes the disclosed scope unreliable.

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, scope first then the paging tip. No filler, nothing redundant with 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?

With no output schema, the description does helpfully reference the returned nextCursor. But it omits the trade record shape and leaves the market-scope conflict unresolved, which matters for a tool whose only hard constraint is stated incorrectly.

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 75% and the schema already documents `before` (nextCursor) and `market`. The description adds only the paging direction for `before`, which is marginally useful; `limit` semantics (default 50, max 200) are never mentioned.

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 ('latest executed trades for an instrument') with the title reinforcing 'time & sales', which clearly separates it from account-scoped siblings like get_closed_trades. However, it does not explicitly name the sibling it is not (e.g. get_closed_trades or get_price_history), so an agent must infer the boundary.

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 one concrete usage instruction ('Use `before` with the returned nextCursor to page back') and a scope constraint ('Egypt only'). It offers no guidance on when to prefer this over get_price_history, get_market_depth, or get_closed_trades, so alternatives are left implicit.

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=true, idempotentHint=true and destructiveHint=false, so the safety profile is largely covered. The description adds real value beyond them by naming the concrete capability boundary — this server cannot move money into or out of savings — which tells the agent not to look for a companion write tool. It does not mention auth requirements or caching, so it stops 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?

The return contents are front-loaded in a single dense sentence followed by a short safety clause; nothing is padded. The parenthetical enumeration is heavy but each element (type, amount, gains, withdrawable amount, yields by frequency) earns its place given the absence of an output schema.

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 correctly carries the burden of describing the return payload, and it does so field-group by field-group. It leaves minor gaps — currency of amounts, scope (account-wide vs per product), and any freshness/refresh semantics — but is otherwise complete for a zero-parameter read tool.

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?

The tool takes no parameters, so the baseline is 4 and there is nothing for the description to disambiguate. Schema coverage is 100% and the empty schema is unambiguous.

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 the exact resource (Thndr savings / 'Clouds') and enumerates what is returned: total amount and gain, per-bundle type/amount/gains/withdrawable, amounts per product type, and per-product yields. No sibling tool overlaps this resource, so the agent can select it unambiguously.

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?

No explicit when-to-use or when-not-to-use statement, and no prerequisite (e.g. authentication) is mentioned. Usage is strongly implied by the unique 'savings' scope and the absence of any competing sibling, which lands at the minimum-viable level rather than clear 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 cover read-only, idempotent, open-world, non-destructive behavior, and the description adds return content: saved screeners/presets with id, name, and plain-language filters. It does not discuss auth, pagination, or error behavior, but the annotation coverage lowers 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 compact sentences front-load what the tool returns and then give the next action. The opening parenthetical about Egypt is slightly misplaced but not verbose.

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 simple read tool with full schema coverage and safety annotations, the description supplies enough output context and usage linkage to call it correctly. The market-scope wording is a minor gap because it only names Egypt while the schema supports four markets.

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% and the market enum is fully documented in the schema. The description adds no parameter semantics and only mentions Egypt, 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 clearly identifies the resource as saved Thndr screeners and ThndrX presets with id, name, and filters, and contrasts it with screen_market for execution. It lacks an explicit verb and leads with a confusing 'Egypt' scope, keeping it short of a 5.

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 explicitly directs the agent to run a screener with screen_market using screenerId or preset, which implies get_screeners is the discovery step. It does not cover when not to use it or other alternatives, so not a 5.

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 safety is covered. The description's field list adds genuine value because there is no output schema, telling the agent what each row contains. It says nothing about ordering, pagination behavior, or which filters combine, so it stays at a baseline-plus level rather than rich.

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 text is a single short sentence with no padding, so it is efficient. But it is a sentence fragment with no verb, which is under-specification rather than disciplined concision for a 7-parameter tool.

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 7-parameter, zero-required-parameter listing tool with no output schema, the description omits the operation verb, usage context, sibling differentiation, and pagination/filter interaction. It gives just enough to guess the payload, not enough to call the tool confidently.

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 71%, which is above the 50% floor but below the 80% mark where the schema alone suffices. The description mentions no parameter at all, so it does not compensate for the unexplained 29% (notably 'page'/'limit' semantics and how period vs from/to interact are only in the 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 fragment names the resource and enumerates row contents (exit price, volume, average entry price, net P/L), so an agent can infer it returns sell executions. However, it has no verb ('get'/'list') and does nothing to distinguish it from close siblings like get_closed_trades or get_realized_returns, leaving the purpose only vaguely bounded.

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 when-to-use or when-not-to-use guidance at all, and no alternative is named. With several overlapping siblings (get_closed_trades, get_realized_returns, get_account_orders), the absence of routing guidance is a real gap.

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 covered. The description adds useful non-annotation context: the response carries price and today's change, and results are paged.

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 dense, front-loaded sentences that state what the tool returns, the identifier forms to supply, and the market scope with zero filler.

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 carry return-value burden and covers it adequately by naming price and today's change plus paging. It could say more about the exact response shape, but nothing essential to calling it correctly is 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 description coverage is 100%, so the schema already documents tag id/slug/name, page, limit and market. The description's tag-identifier hint and 'Egypt and US' note largely restate what the schema says, 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 states a specific verb and resource — the instruments belonging to one Thndr tag/theme in a given market — and grounds it with concrete examples (Sharia-compliant EGX stocks, gold funds). This is clearly distinct from search_instruments and get_tags, so an agent can select it 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 a clear prerequisite/pointer — "Give the tag's id, slug or name (see get_tags)" — and scopes the tool to Egypt and US markets. It doesn't explicitly state when to prefer this over search_instruments, but the context is unambiguous.

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 safety is covered. The description goes beyond them by describing the shape of what comes back (what each tag is about, how many instruments it holds) — valuable since there is no output schema — and by narrowing market scope to "Egypt and US."

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, front-loaded with the resource definition and followed immediately by the sibling routing. Every clause carries information; there is 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?

With no output schema, the description usefully sketches what a tag record contains and where to go next for detail, which is enough to call the tool correctly. It does not address ordering, whether all tags are returned at once, or reconcile the market enum's "uae"/"simulator" values with the stated "Egypt and US" scope.

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 parameter has an enum with a default, so the schema already carries the baseline. The description adds scope meaning the schema does not convey — that only Egypt and US are supported — which is genuinely useful even though it sits in tension with the enum listing "uae" and "simulator".

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 resource (Thndr's tags/themes for a market), explains what they are with concrete examples ("Sharia", "Gold Funds", "Dividend Players"), and notes the payload includes a description and instrument count. It explicitly differentiates itself from the two closest siblings, so an agent can pick it without opening another 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?

Names both adjacent tools and their distinct jobs ("List a tag's instruments with get_tag_instruments; get_instrument_details shows the tags of one instrument"), which effectively routes the agent. It stops short of an explicit when-to-use trigger for this tool itself (e.g., "call this first to discover available themes"), so it is strong but not fully prescriptive.

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 and openWorldHint, so safety is covered. The description adds nothing behavioral beyond that – no note on data freshness, whether results are live vs. simulated, or how market/period interact. It essentially only lists output fields.

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?

A single front-loaded sentence with no filler. It is efficient, though the comma list of metrics is somewhat dense and could be organized, keeping it short of a 5.

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's enumeration of returned metrics is genuinely useful and partially compensates. However it omits scope (account-level? all accounts?), grouping, and any usage context, so it is only minimally adequate for a four-parameter analytics tool.

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 all four parameters (from, to, market, period) are fully documented in the schema, including enum values and the 'do not combine with from/to' constraint. The description adds no parameter detail, which is acceptable given the schema does the work.

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 says it returns performance statistics and enumerates them, which conveys the resource. But it never states scope or verb precisely, and with siblings like get_portfolio_performance, get_realized_returns and get_closed_trades all plausibly overlapping, an agent gets no help telling them apart. Vague purpose rather than a distinguishing statement.

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 when-to-use, when-not-to-use, or alternative-tool guidance at all. Nothing indicates whether this covers a single account, all accounts, or how it relates to get_portfolio_performance or get_realized_returns.

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 non-structured behaviour: results are ranked 'most trending first' and mirror the app's Explore tab ordering, plus the returned field set. It does not discuss freshness or refresh cadence, which would be the remaining piece.

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?

A single sentence that front-loads the core purpose and ordering, then names the returned fields, then the alternative tool. No filler, nothing repeated from 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 usefully enumerates what is returned (ticker, name, asset class, sector) and the ranking semantics, which is what an agent needs to decide relevance. Missing only minor operational detail such as default limit behaviour, which the schema carries.

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 parameters are already documented and a baseline of 3 applies. Note the description's market list ('Egypt, US or UAE') omits the 'simulator' enum value that the schema includes, so it adds no meaning beyond the schema and is slightly narrower than it.

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?

Specific verb+resource with scope: it states the tool returns instruments trending on Thndr per market, in rank order, matching the Explore tab, and enumerates the returned fields. An agent can distinguish it from price-serving siblings at a glance.

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 explicitly routes the agent elsewhere for prices ('Use get_price_snapshot for their prices'), which is a real alternative-selection cue. It gives no explicit when-not guidance relative to near-neighbours like get_market_movers, so it stops short of the top band.

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=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds one behavioral detail—that the result includes instruments—but does not cover return format, errors, or permission needs, making it minimally additive.

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?

A single, front-loaded sentence with no filler. Every word contributes to defining the tool's scope and return composition.

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 simple read tool with annotations covering safety, the description gives the essential scope (single watchlist by id, includes instruments). However, with no output schema, it omits any description of the returned watchlist structure or the market parameter's role, leaving gaps an agent might need.

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?

With 50% schema description coverage, the market parameter is fully documented in the schema, while id only has minLength. The description's 'by id' minimally reinforces the id parameter but adds no format or constraint detail beyond the schema, so it neither compensates for nor exceeds the schema baseline.

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 the resource (a watchlist) and scope (one, by id, with instruments), which implies retrieval and distinguishes it from get_watchlists. However, it does not name any sibling tool explicitly and lacks an action verb, so it falls short of the highest clarity bar.

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?

No guidance is given on when to use this tool versus get_watchlists or other watchlist operations. The agent must infer that 'one by id' means a single retrieval, with no exclusions or alternatives stated.

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, destructiveHint=false and openWorldHint, so the safety profile is fully covered. The description adds what is returned (instruments with tickers and asset ids), but says nothing about auth requirements, pagination, or behavior on an empty watchlist set.

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?

One sentence, front-loaded with the resource, no filler or restated title boilerplate. Every clause earns its place.

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 read-only listing tool with full annotation coverage and a fully described single parameter, the description covers what the tool does and roughly what comes back. It stops short of noting the market scoping interaction or empty-result behavior, but nothing essential to calling it correctly is 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 description coverage is 100% and the single market parameter is fully documented with its enum values and defaults in the schema. The description contributes no additional meaning about market scoping, so the baseline of 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+resource ('All custom watchlists of the Thndr account') and even names the payload fields returned (tickers, asset ids). It is clearly a plural listing tool, but it never explicitly distinguishes itself from the singular sibling get_watchlist, leaving that distinction to inference.

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 when-to-use, when-not-to-use, or alternative-routing guidance. With siblings get_watchlist, create_watchlist, edit_watchlist and delete_watchlist in the same namespace, the description gives no help on which to pick; the word 'All' is the only implicit signal.

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 flag this as non-read-only, idempotent, and open-world, so the safety profile is known. The description adds real behavioral context beyond that: it blocks for up to timeoutSeconds, persists the session, and can return a pending status requiring a repeat call.

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 step position and action, then the waiting semantics, then the retry condition. Every sentence carries information an agent needs.

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 usefully surfaces the return signal (authenticated=false with status pending) and the polling expectation. Nothing an agent needs to call this correctly is 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?

Only one parameter exists and the schema documents it at 100% coverage, so the schema does the heavy lifting. The description's '(up to timeoutSeconds)' merely echoes the parameter name without adding format or default detail.

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 action (waits for approval, then stores the session) on a specific resource (the Thndr login session), and its 'Step 3 of 3' framing clearly separates it from the sibling login_verify_code and login_request_approval steps.

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 places the call in the login sequence and gives a concrete retry rule: if it returns authenticated=false with status pending, call again after the user approves. It doesn't name alternative siblings to avoid, but the step ordering plus retry condition cover the practical when-to-use case.

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=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description adds important out-of-band context: the user must manually log in via browser and extract the Cookie header from DevTools, which is not in 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?

One front-loaded sentence with no filler; the colon structure separates purpose from mechanics. Every clause earns its place.

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 login tool with annotations and no output schema, the description covers what it is, when to use it, and how to obtain the required input. It omits what happens after a successful call (e.g., session establishment or returned token), but that is a minor 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 100% and the single parameter is documented. The description adds meaning by explaining where to obtain the cookieHeader (DevTools → Network, any x.thndr.app/api request), which goes beyond the schema's 'value of the Cookie header'.

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: a fallback login that imports a browser session by pasting a Cookie header. It distinguishes itself from the other login_* siblings by scoping to accounts that use Google/Apple sign-in.

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 a clear condition for use: accounts that use Google/Apple sign-in. It does not explicitly name alternative tools or state when not to use it, so it falls short of full routing 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 write semantics (readOnlyHint=false), non-idempotency and non-destructiveness, so the safety profile is covered. The description adds real behavioral context beyond that: approval happens out-of-band in the Thndr mobile app, no email code is involved, and the flow continues at login_complete. It doesn't mention request expiry or how approval status is observed, which keeps it from 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?

Three short sentences, front-loaded with the action, then the trigger condition, then the follow-up tool. Every sentence carries distinct, actionable information with no repetition of the title or annotations.

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 zero-parameter auth-flow step, the description supplies the essential context: precondition, out-of-band approval mechanic, and the next call to make. It leaves the caller without any indication of timing/expiry or how to detect a declined approval, which is the only meaningful remaining gap given there is no output schema.

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?

The tool takes zero parameters, so the schema-baseline of 4 applies; there is nothing for the description to disambiguate and it correctly introduces no invented inputs.

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 ('Creates a new login request') and immediately scopes it ('for an already identified user (no email code needed)'), which cleanly separates it from the email-code siblings like login_start/login_verify_code. An agent can tell what this does and which flow branch it belongs to without opening the 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?

Gives an explicit trigger ('Use it when the session expired (SESSION_EXPIRED)') and an explicit successor ('Next: login_complete'), which is strong routing guidance. It stops short of naming a when-not-to-use case or the alternative tool by name, so it falls just below the top bar.

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 declare openWorldHint=true and non-idempotent, indicating an external, non-repeatable side effect. The description adds that a code is sent to the user's email, which is useful behavioral context. It doesn't mention rate limits or code expiration, but given annotation coverage, this is solid.

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 step number and primary action. Every sentence adds value: the action, the prerequisite, and the next step.

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 the single-parameter schema and annotations, the description is nearly complete. It covers the action, prerequisite, and next step, but omits any note on code expiry or error handling, which would be helpful for a multi-step authentication flow.

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?

Only one parameter (email) with 100% schema description coverage, so the baseline is 3. The description adds no syntax or format details beyond what the schema provides.

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 action (sends a 6-digit verification code) to a specific resource (the Thndr account email), and explicitly positions itself as 'Step 1 of 3' in the login sequence. This clearly distinguishes it from sibling login tools like login_verify_code and login_request_approval.

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 instructs the agent to ask the user for their email if unknown, and names the next step ('Next: login_verify_code'), providing both prerequisite context and workflow routing.

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=false, idempotent=false, openWorld=true, destructive=false. The description adds context annotations cannot carry: the login request requires out-of-band approval in the mobile app, and the returned message/deep link must be surfaced to the user. It omits failure modes (wrong/expired code, retry limits), so it is strong but not exhaustive.

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, zero filler, and the flow position is front-loaded so the agent immediately knows the ordering. Every sentence carries actionable information (what it does, what to show the user, what comes next).

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 multi-step auth tool with no output schema, the description covers the essentials: its place in the flow, the side effect it creates, what is returned (message + deep link), how to present it, and the next call. Nothing needed to invoke or route it correctly is 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?

With a single parameter and 100% schema description coverage ('The 6-digit code from the email'), the schema already carries the full parameter contract. The description's 'emailed code' phrasing adds no format, source, or constraint detail beyond it, 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 ('Verifies the emailed code') plus the side effect it triggers ('creates a login request that the user must approve in the Thndr mobile app'). The 'Step 2 of 3' framing and the named successor distinguish it cleanly from login_start, login_complete, and login_request_approval without opening any 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?

Explicit sequencing ('Step 2 of 3', 'Next: login_complete') tells the agent where this sits in the auth flow and which sibling follows. It also instructs what to do with the result ('Show the user the returned message (and deep link)'). It does not state when-not to call it (e.g., expired/invalid code handling or when to restart at login_start), so it stops short of a 5.

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 declare destructiveHint and idempotent, and the description adds concrete detail: it deletes stored tokens and conditionally signs out of Firebase. Adds value beyond annotations, though it doesn't cover reversibility or post-logout state.

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, front-loaded with the primary action and immediately qualifying the parameter behavior. No waste.

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?

Covers the core action, token deletion, and the parameter's effect for a single-param tool. Missing minor details like whether the caller must re-authenticate afterward, but adequate given no output schema.

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 0% and forgetIdentity has no description in the schema. The description compensates by explaining exactly what forgetIdentity=true does (also signs out of Firebase), supplying the missing semantics.

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 (ends session, deletes tokens) on a specific resource (Thndr session). Clearly distinct from sibling login_* tools and read-only getters.

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?

Implies this is the way to terminate a session, and the forgetIdentity clause hints at when extra behavior applies. No explicit when-to-use/when-not guidance relative to auth_status or session-import tools.

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 idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so the mutation safety profile is covered. The description adds the useful scope distinction that all=true affects every notification, which is context beyond the annotations, but it says nothing about permissions, reversibility, or interaction when both ids and all are supplied.

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?

One sentence, front-loaded with the action, no filler or redundant 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 simple two-parameter mutation with no output schema and annotations covering safety, the description gives an agent enough to call it correctly. The only gap is the unspecified precedence when both 'ids' and 'all' are provided.

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 0%, so the description carries the full burden and largely discharges it: it explains that 'ids' are the notifications to mark and 'all=true' marks everything. It does not mention the 200-item cap or the precedence between the two params, but the core semantics of both parameters are supplied.

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?

Specific verb+resource: 'Marks the given notification ids as read'. An agent can immediately distinguish this mutation from the sibling read tool get_notifications. It does not explicitly name the sibling, but the read/write contrast is unmistakable.

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 two invocation modes (specific ids vs. all=true) but gives no explicit when-to-use guidance, prerequisites, or warnings about the bulk 'all=true' path. No alternative tools are referenced, though none really compete here.

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 cover read-only, idempotent, open-world and non-destructive behavior. The description adds real context beyond them: filters are conjunctive ("All given filters apply together") and index rows are excluded from results, both genuine behavioral facts an agent could not infer from structured fields.

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?

One dense, front-loaded sentence that opens with scope before listing use cases; nearly every clause maps to a real parameter, so little is wasted. It is long enough to read as a run-on, but the examples earn their space.

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 17 parameters, no required fields and no output schema, the definition covers the filtering half well but says nothing about what a result row contains or how limit/pagination behaves beyond the schema default. The "Egypt only" claim also leaves an agent unsure whether market=us/uae works, which is a real gap for a 17-param tool.

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 only 47%, so the description must compensate, and it does explain several parameters through working examples (sortBy=changePercent, order=asc, minRelativeVolume=200, maxPeRatio, minDividendYield, index=EGX30, preset names, screenerId). However it incorrectly states "Egypt only" while the schema's market enum accepts us/uae/simulator, and it leaves limit, includeSuspended, min/maxPrice and min/maxChangePercent untouched, so the compensation is partial and partly misleading.

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?

Specific verb+resource: "filter and rank every instrument of the market using the live snapshot", with an explicit scope. It clearly distinguishes itself from siblings like get_market_movers (fixed movers lists), get_screeners (saved screener listing) and get_index_constituents, which it references rather than duplicates.

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?

Offers concrete when-to-use recipes (top gainers, top losers, most active, unusual volume, value stocks, sector, index members, preset, saved screener) and routes the agent to get_screeners and get_index_constituents for supporting ids. It never states when to prefer a sibling such as get_market_movers instead, so it stops short of full explicit alternatives.

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 cover the safety profile (readOnly, idempotent, openWorld, non-destructive), so the description's job is to add context — which it does by disclosing the return content (tickers and Thndr asset ids) and multilingual query support. It stops short of noting pagination or result-count behavior tied to limit.

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 tight sentences, each doing distinct work (scope, return values, usage ordering). The most actionable guidance ("call this first") is saved for the end as a clear directive, with no filler.

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 correctly compensates by naming what is returned. It covers scope, key, languages, and usage ordering; the only omission is any hint about the limit/paging behavior, which is a minor gap for a search tool.

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 67% and already documents query and market, but the description adds value the schema lacks: asset-type scope and that queries work in English or Arabic. The limit parameter remains undocumented in both places, which caps this below a 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 (search) and resource (instruments), scopes the asset types (stocks, ETFs, funds, indices) and the lookup key (ticker or company name). This clearly separates it from siblings like get_instrument_details and screen_market without opening either 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?

"Call this first when you only know a company name" gives explicit sequencing guidance and implies the downstream alternative (get_instrument_details by id). No explicit when-not condition or named alternative, which keeps it just short of a 5.

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 cover the safety profile (mutation, non-idempotent, non-destructive), but the description adds a genuinely non-obvious consequence: the alert is replaced and receives a new id, returned alongside previousId. That is exactly the kind of behavior an agent could not infer from the schema or annotations, and it is consistent with idempotentHint=false.

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 tightly written sentences with no filler, and the primary action is front-loaded ahead of the replacement caveat. Every clause carries information the agent needs.

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 mutation tool with no output schema, the description closes the most important gap by explaining the return values (new id plus previousId) and the replace semantics. Combined with the annotations and the 80%-covered schema, an agent has enough to call it correctly.

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 schema already documents most parameters including enums and defaults. The description names the three mutable fields (price, direction, frequency) but adds no format, constraint, or default detail beyond what the schema provides, so the 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 ('Changes an alert's price, direction or frequency'), which an agent can distinguish from create_alert/delete_alert/get_alert. It stops short of naming any sibling explicitly, so the differentiation is inferred rather than stated.

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 guidance, no prerequisites, and no routing to alternatives such as create_alert or delete_alert. The closest thing to usage context ('Thndr has no in-place edit') is really a behavioral trait, not selection guidance.

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