TradeAlmanac

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds non-derivable behavior: the data is the platform's own estimate rather than exchange data, and status=absent signals an unpublished value for the date. Useful provenance and error-state semantics, though nothing on freshness or update cadence.

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

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

Four tight sentences, each doing work: identity, alternative, provenance, error state. The clause 'value on a 0–100 scale, zone and date' mildly duplicates the output schema, which is the only slack in an otherwise lean definition.

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 an output schema present, the description does not need to enumerate return fields, yet it still flags the three headline ones. Combined with routing advice, provenance, and status=absent handling, an agent has everything needed to call this zero-parameter tool 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. Schema coverage is 100% and the description correctly adds no phantom parameter guidance.

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 (the Fear & Greed Index of the Russian market) plus its scale and outputs, and immediately frames the cryptic name 'afgi' as a legacy alias. An agent can tell it apart from get_indicator and afgi_history from this text 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?

Explicitly says to prefer get_indicator with spec_id afgi because it also returns the components, and identifies the only case for using this tool instead (old clients pinned to the old name). This is a genuine when/when-not/alternative statement.

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 read-only, idempotent, closed-world, non-destructive behavior. The description adds genuinely new context beyond them: the figure is the platform's own estimate rather than an exchange number, and status=empty signals an empty period rather than an error. Pagination/limit behavior is left to the schema, 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 tight sentences, front-loaded with the legacy-name framing, then the preferred alternative, then the caveat and status semantics. Every sentence carries information; the dense em-dash payload sentence is slightly packed but not wasteful.

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

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

An output schema exists, so return shape needn't be spelled out, and the description still covers the key interpretive caveats (platform estimate, status=empty). Only minor gaps remain, such as default-window or pagination behavior, which the schema partially covers.

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 limit default (180), min/max, and date_from/date_to formats already documented. The description only restates the notion of a period, adding no format or edge-case detail beyond the schema, 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?

States a specific resource and payload: daily Fear & Greed Index values for the Russian market over a period, with value/zone/date fields. It also flags itself as a legacy alias and names the sibling that supersedes it, so an agent can distinguish it from get_indicator_history 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?

"Prefer get_indicator_history with spec_id afgi" gives an explicit alternative and the exact parameterization to use it. Combined with 'kept for old clients', the when-to-use condition (backward compatibility only) 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 cover the safety profile (readOnlyHint=false, destructiveHint=false), and the description goes well beyond them: it discloses firing cadence (once per trading day; checked daily on closed values), idempotent re-request behaviour for world_price_target and composite_zone_change (returns the existing rule with created=false), the quota ceiling, and the permission required. It also warns that the call mutates the account. No contradiction with annotations — the per-type idempotency note refines, rather than conflicts 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?

Front-loaded with the core action and effect, then organized per rule_type, so the structure is easy to scan. It is very long, and the zone-scale enumeration (extreme_fear/fear/neutral/greed/extreme_greed with numeric bounds) is verbose, but almost all of it is load-bearing given the five distinct rule shapes.

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 complex tool with a nested params object and five variants, the description covers selection, per-type arguments, mutation semantics, idempotency, limits, permissions and the user-facing constraint on near misses. An output schema exists, so return values need not be elaborated, yet the created/rule_id shape is briefly and harmlessly confirmed.

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?

Top-level schema coverage is 100%, but the nested params object is entirely undocumented in the schema ('as listed in the tool description'), so the description carries the full burden and does so precisely: it names every sub-field per rule_type (threshold, currency, market, symbol, price, direction, slug, price_usd, spec_id, zone) with types, units and which are required. It also explains the ticker applicability rule and the zone-only representation of indicator thresholds.

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 ('Create an alert rule in the user's account') and immediately describes the observable effect (notification in the notification centre and enabled channels). It is trivially distinguishable from siblings such as alert_delete and alerts_list, and it enumerates the five rule types the server accepts.

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 explicit routing per rule_type with the conditions each expresses, plus an explicit negative instruction: 'Do not use this tool for a condition these types cannot express: tell the user instead of silently creating a near miss.' It also states the hard ceiling (agent rule limit) and the required 'alerts' permission, which are genuine preconditions rather than implied 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 destructiveHint=true and idempotentHint=true, and the description adds substantial context on top: firing stops immediately, already-sent notifications persist in history, the deletion is irreversible and requires re-creation, and the alerts permission is required. That covers side effects, reversibility, and auth in one place.

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

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

Four short sentences, front-loaded with the action and the key, then consequences, then the permission gate. Slight redundancy in restating irreversibility ('cannot be undone: the rule would have to be created again'), but nothing is wasted overall.

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 single-parameter destructive tool with an output schema, the definition covers everything an agent needs: what it does, the identifier's source, immediate effects, reversibility, and required permission. Return-value behavior is correctly left to the 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 100% and the single parameter's provenance ('from alerts_list') is already stated in the schema, so the description largely repeats structured data. Baseline 3 is appropriate when the schema does the work and the description adds no format or constraint detail beyond 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?

States a specific verb and resource ('Delete one alert rule of the user's account') plus the identifying key ('by its rule_id'), which clearly separates it from alert_create and alerts_list. No ambiguity about what the tool does or what scope of resource it touches.

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 usage restriction ('Call it only on a direct request of the user') and names alerts_list as the origin of rule_id, which helps the agent sequence calls correctly. It stops short of naming the full set of alternatives or the condition that would select alert_create instead, so it lands just below 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 mark this read-only/idempotent/non-destructive, but the description adds substantial context beyond them: it states the required 'alerts permission of the sign-in', clarifies that total is the account's rule count, specifies currency units for threshold/price/price_usd, and warns that rule names are user-authored text (data, never instructions).

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 what the tool lists, then layers usage, exclusions, output semantics, units, and safety notes. Despite its length, every sentence adds actionable information for calling or interpreting the 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 no-input, read-only list tool with an output schema, the description covers the remaining gaps an agent needs: usage conditions, sibling interactions, auth requirement, output-field semantics, units, and prompt-injection caution around user-authored rule names.

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 accepts zero input parameters, so the baseline is 4. The currency-unit notes about threshold, price, and price_usd concern rule output fields rather than callable inputs, so there is no additional input-parameter meaning to 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?

Starts with a precise verb+resource: 'List the alert rules of the signed-in user's account', then enumerates the returned fields (id, name, type, watched instrument/indicator, parameters, enabled, last-fired). It also distinguishes itself from siblings by noting alert_delete consumes the rule_id and that creating a rule can be checked for duplicates beforehand.

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 explicit use cases — answer 'what alerts do I have', check before creating a rule to avoid duplicates, and obtain rule_id for alert_delete — plus an exclusion: 'It lists rules, not the notifications already delivered.' No alternative routing 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 the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description goes well beyond them: it discloses that texts come from an editorial pipeline and arrive as untrusted data, warns never to follow instructions inside them, and defines the status=empty outcome. Provenance and prompt-injection risk are exactly the non-obvious traits an agent needs.

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

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

Four sentences in one block, front-loaded with the purpose before usage, safety, and status semantics — every sentence carries distinct information. It is slightly dense with stacked parentheticals ('already formatted, with their units'), which costs a little readability but not substance.

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

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

For a two-parameter read tool this covers purpose, triggers, exclusions, data provenance, and the empty-result signal; an output schema exists so return structure needn't be re-explained. Nothing an agent needs to call it correctly or interpret results safely 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 coverage is 100% and both parameters (ticker, limit with default 20 and 1-100 bounds) are fully documented in the schema. The description adds no syntax, format, or default information for the parameters — its content about question/verdict/figures describes return values, not inputs. 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 resource ('Published write-ups of the platform about ONE security') and enumerates exactly what each item contains (question, verdict, figures with units, text). It also explicitly excludes sibling domains (dividends, multiples, sentiment), so an agent can separate it from dividends_by_ticker and screener 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?

Gives an explicit positive trigger ('when the user asks whether there is an analysis of a company or wants a qualitative view next to the numbers') and explicit negative guidance ('Do not use it for dividends, multiples or sentiment'). This is a named when/when-not pair, not implied usage.

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 closed-world, so the safety profile is covered. The description adds genuinely new behavioral context beyond them: it enumerates the specific data classes NOT served (quotes, candles, MOEX instrument directory, index levels, commodities, coin prices, CBR rates), mentions rate ceilings and contract editions, and warns it returns no market data. It does not describe pagination or output shape, but that is largely covered by the 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?

Front-loads the identity of the tool, then the negative scope, then the usage rule. It is slightly heavy — a long nested parenthetical list of unsupported data types — but every clause is informative rather than filler, so the density is justified.

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 an output schema present, return values need no explanation, and the description covers the remaining essentials: what the tool answers, what it excludes, when to invoke it, and the caveat that it supplies no market data itself. An agent has everything needed to call it correctly and to interpret an empty or negative answer.

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% for the single 'lang' parameter (en/ru, defaults to server language), so the schema already carries the semantics. The description never mentions the language parameter or how it affects the returned texts, adding nothing on top of the structured field.

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, unusual purpose: the API describing its own coverage, both what it serves and what it explicitly does not. The closing line 'It returns no market data itself' cleanly separates it from data-bearing siblings such as market_overview, screener or world_benchmarks.

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 explicit triggers: 'when the user asks what the service can do' and 'when a question needs data you are not sure the service has', with concrete examples (share price, intraday candles, foreign company, coin price). It even specifies the decision point — call this 'before answering that it is not available' — which is the precise failure mode it prevents.

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?

Adds substantial context beyond the readOnly/idempotent annotations: rates fixed once per working day, informational only (not a tradeable quote), cross rates computed by TradeAlmanac vs. ECB-published reference rates, mandated citation of the ECB and as_of, and explicit out-of-scope currencies. This is exactly the behavioral disclosure 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?

Front-loaded with the resource and ordering, but the second half packs citation rules, kind semantics, and the rouble caveat into dense run-on sentences. Every sentence earns its place, yet the structure is heavy and could be trimmed 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?

An output schema exists so return fields needn't be restated, and the description still covers provenance, publishing cadence, cross-rate computation, and required citation. It is essentially complete for an agent to call and correctly attribute this zero-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?

Zero parameters, so baseline is 4. The description still documents the row fields (pair, base, quote, rate, change_pct, as_of, kind) and the units of rate, which helps an agent interpret output even though no input params exist.

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 (ECB euro foreign exchange reference rates) with scope spelled out: the major currency pairs and main cross rates, in currency-page order. It clearly distinguishes itself from siblings like world_benchmarks or market_overview by being the FX reference-rate 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?

Ends with an explicit when-to-use trigger: 'when the user asks for an exchange rate between major currencies, or how a currency moved against the dollar or the euro at the last publication.' It also names the exclusion (no rouble, no Bank of Russia rate). Lacks a named alternative sibling, but the positive condition is concrete.

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 a safe, idempotent read, so the bar is lower, yet the description adds substantial domain behavior: amounts are per share in the currency field, yields are fractions (0.08 = 8%), forecast payouts are board-unapproved and must never be presented as declared, and status=empty and null have precise, non-intuitive meanings. This is exactly the context 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 purpose, then use conditions, then exclusions, then unit/status semantics. Every sentence carries agent-relevant information; the dense semantics block earns its length because it prevents misinterpretation of empty and null values.

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?

An output schema exists, so return values need no narration, yet the description still disambiguates the field semantics that agents most often misread (yield fractions, null vs zero, empty status). Combined with read-only annotations and a fully documented single parameter, nothing needed to call or interpret it 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 coverage is 100% and the single ticker parameter is documented with examples (SBER, LKOH, GAZP), so the schema already carries the input semantics. The description elaborates on output fields (currency, yield fractions) rather than adding input meaning. Baseline 3 is correct.

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 (dividend history and next payout), scope (ONE security on the Moscow Exchange), and access key (by ticker). It explicitly names the siblings it is not (dividends_calendar, screener), so an agent can route 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?

Gives an explicit use condition ('when the question names one company or ticker and asks what it paid, when the record date is, or what its dividend yield is') and explicit exclusions with named alternatives for both other cases (dividends_calendar, screener). Nothing 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: the default window starts from the oldest records if dates are omitted, status=empty means no record date in range, pagination continues via the next_cursor cursor, and total counts payouts in range. These are operational traits an agent cannot infer from 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?

Front-loaded with the scope sentence, then usage, then the date-range warning, then return-field notes. Mostly tight, but the trailing output-field explanations (yield_current fractions, total, next_cursor) partly restate what the existing output schema already provides.

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?

An output schema exists, so return-shape explanation is optional, yet the description still supplies the units and edge-case semantics (per-share amounts, currency field, status=empty, pagination) that make the tool unambiguous to call 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 description coverage is 100%, so the baseline is 3. The description's parameter guidance (YYYY-MM-DD format, consequence of omitting dates, cursor source) largely duplicates what the schema already states for date_from, date_to, limit and cursor, adding emphasis rather than 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+scope: 'Dividend record dates of ALL Moscow Exchange securities inside a date range, with the announcement status of every payout.' It explicitly names the sibling it is NOT for (dividends_by_ticker), so an agent can route 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?

Gives concrete triggering questions ('who pays in December', 'which record dates fall on next week') and an explicit exclusion naming the alternative tool. When-to-use, when-not-to-use and the alternative are all present.

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, closed-world), and the description adds genuinely new behavioral context: the units of mean_return/median_return/positive_share (fractions, 0.0125 = 1.25%), the meaning of n and of p_adjusted as multiple-comparison-corrected, and an interpretive constraint that nominally significant effects must not be presented as regularities. That is substantive guidance beyond 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?

It is a dense single block but front-loads the core purpose, then scope, then usage, then units, then caveat. Nearly every sentence earns its place, though the family/code enumeration slightly overlaps the schema and could be trimmed.

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 statistics tool with an output schema, the description covers everything needed: what it returns conceptually, how to read the numeric fields, and how to interpret significance. Nothing an agent needs in order to call or interpret 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 code, family and subject including the 'omitted — all' default and the weekday_1 = Monday example. The description largely repeats that (family list, code examples), adding little syntax or semantics beyond what the schema provides, so the baseline 3 applies.

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

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

The description states a specific verb+resource (calendar effects computed from history) and enumerates the exact scope: subjects IMOEX/RGBITR and the five effect families with their code prefixes. An agent can distinguish this from siblings like analysis_by_ticker or get_indicator 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 concrete trigger phrasings ('is there a January effect', 'are Mondays weak', 'what happens around rate decisions') and an explicit exclusion ('Do not use it for a forecast or for one stock'), which is exactly the when/when-not/alternative routing an agent needs.

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 bar is lowered; the description still adds real behavioral context: components are on the same 0–100 scale, weights are fractions summing to 1, raw input values are not served, and status=absent means unpublished rather than zero. It does not discuss pagination or auth, but for a single-value read that is minor.

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 content is dense but front-loaded: what it returns, when to use it, when not to, then the semantic caveats. Every sentence carries information, though the run-on identifier list and caveats make it slightly heavy for a one-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?

An output schema exists so return values need not be explained, yet the description still maps the returned fields (value, zone, date, methodology version, components, weights). Combined with the absence semantics and cross-references to list_indicators, an agent has everything needed to call and interpret 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 coverage is 100% and the single parameter is documented in the schema, so the baseline is 3. The description goes beyond it by naming valid identifiers, explaining that sector/Bitcoin/Ether identifiers must come from list_indicators, and clarifying that spec_id is an indicator identifier.

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 ('Current value of ONE indicator by identifier') and enumerates exactly what is returned: value, zone, data date, methodology version, and normalised components with weights. It explicitly distinguishes itself from get_indicator_history and list_indicators, so an agent can route correctly 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 an explicit positive trigger ('when the user asks what an index shows now and what it is made of') and an explicit exclusion with the alternative named ('Do not use it for a series over time (get_indicator_history)'). Concrete identifier examples (afgi, us_sentiment, crypto_fear_greed) further clarify the scope.

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 the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context beyond that: an API key unlocks full history while keyless access is capped at the last year, cut periods are flagged depth_limited, status=empty signals no values, and it clarifies this is a platform estimate rather than exchange data. These are exactly the behavioral traits 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-loads the core purpose in the first sentence, then layers usage, key/coverage behavior, output field meanings, and failure status. It is dense and multi-topic, but every sentence carries decision-relevant information; slightly crammed rather than 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?

An output schema exists, so return values need not be enumerated, yet the description still explains the notable fields (as_of, as_of_oldest, status=empty, depth_limited) and the key-based coverage limit. For a read-only historical series tool, this is complete enough to call 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 100%, so the schema already documents all three parameters including the YYYY-MM-DD formats. The description restates the date format but adds no syntax or constraint beyond the schema, so the baseline 3 applies. Its extra semantics (as_of, depth_limited) describe output, not parameters.

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 (serve a daily series) and resource (ONE indicator) with explicit scope (over a period) and names what it returns (date, value 0–100, zone, methodology version). It also differentiates itself by naming siblings get_indicator and list_indicators as the wrong choices for a single point-in-time value.

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 explicit when-to-use ('how has the index changed since…' and for a chart), when-not-to-use (when only the current value is needed, routing to get_indicator or list_indicators), and the parameter format (date_from/date_to as YYYY-MM-DD). Nothing 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, non-destructive, and closed-world, so the safety profile is covered. The description goes further by disclosing output limitations ('no price, no size of the fall and no multiples'), the exact unit convention for discounts (-84.47 means −84.47 %), and a non-recommendation disclaimer. It does not discuss staleness/refresh of the snapshot or rate limits, but for a read-only snapshot the added context is substantial.

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 primary purpose is front-loaded in sentence one and every later sentence carries information (use cases, units, output caveats, disclaimer). It is dense and slightly long, especially the enumerated timeframes, but there is no filler 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?

With an output schema present, return values need not be re-explained, yet the description still warns about what the answer lacks and how to interpret discounts, which covers the tool's main trap. Details such as the meaning of 'changes in the line-up' and how the selection rules are conveyed remain inferential, but nothing needed to invoke 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 coverage is 100% so the baseline is 3, but the description adds meaning beyond the schema by explaining what each ranking_id value is for and by defining the unit of the discount values returned. The lang parameter's effect on names is left to the schema, which is acceptable at full coverage.

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

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

The opening sentence states a specific verb and resource ('The latest snapshot of ONE ranking') and enumerates the payload (place, ticker, name, sector, changes in line-up, selection rules). The word 'ONE' plus the contrast with screener clearly separates it from list_rankings and screener. An agent can identify the tool 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?

It gives explicit use cases mapped to ranking_id values: 'which stocks are undervalued' → undervalued_relative, and 'which fell the most over a day / week / month / three months / year' → the fallen_* variants. It also routes the agent elsewhere for valuation multiples ('multiples come from screener'), which is a genuine when-not-this-tool 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds real domain context: values are the platform's own estimates on a 0–100 fear/greed scale, not exchange data and not a price, and each row carries its own as_of date. It does not discuss volume, pagination, or staleness of the data, so it falls short of full behavioral 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?

Three sentences, front-loaded with the resource and its row contents, then usage, then data-semantics caveats. Every sentence carries information, though the market enumeration and the caveat about estimates make it denser than strictly necessary.

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?

An output schema exists, so return values need no further explanation, and the definition still alerts the agent to the 0–100 scale meaning and the per-row as_of date. For a zero-parameter list tool, nothing an agent needs to select or call 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?

The tool takes zero parameters, so there is no parameter semantics to explain; the baseline of 4 applies. The description correctly avoids inventing filters and clarifies row-level fields instead.

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 (all platform-calculated indicators) plus the exact columns returned — identifier, current value, scale zone, as_of date — and enumerates the covered markets (Russian, US, crypto, Bitcoin, Ether). It also distinguishes itself from get_indicator and get_indicator_history by framing itself as the discovery/lookup 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?

Explicitly states when to use it: to answer 'which indicators exist', when a single current value suffices, or to obtain the identifier needed by get_indicator and get_indicator_history. It names the alternatives and the condition that routes to them, leaving nothing to inference.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description still adds real behavioral value by saying the output carries the date and size of the latest snapshot, which tells the agent the result is a catalogue with freshness metadata rather than raw data rows.

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?

Purpose is front-loaded in the opening clause, and the identifier enumeration is dense but earns its place because those identifiers are the vocabulary the agent needs to route into get_ranking. The identifier glossary is long and could arguably live in the output schema, but it is not padding.

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

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

With an output schema present, annotations covering safety, and a single fully-documented optional parameter, the description supplies exactly the missing pieces: what the tool lists, when to call it, and which sibling to call next. Nothing an agent needs to select or invoke it correctly is 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?

Only one parameter, and schema description coverage is 100% with the lang enum values (en, ru, de) and default fully documented in the schema. The description contributes nothing about language handling, which is acceptable given the schema does the work, but leaves it at the 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?

States a specific verb and resource ('ready-made stock rankings of the platform') and enumerates the concrete identifiers the tool exposes (undervalued_relative, fallen_1d/1w/1m/3m/1y), so an agent immediately knows what this returns. It is unambiguously distinct from the sibling get_ranking, which is named and described as the data-fetching 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?

Explicit trigger ('Use it when the user asks which rankings exist') plus an explicit alternative and the transition condition ('For the line-up itself call get_ranking with the identifier — the identifiers above can be passed straight away'). This is a textbook metadata-vs-data routing instruction with no inference required.

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 a read-only, idempotent, non-destructive profile, but the description goes further by disclosing null semantics ('hours=null means the market has no single schedule; instruments=null means there is no count') and clarifying that hours are the regular schedule rather than a live state. That is genuine behavioral context 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?

It is front-loaded with the resource and its fields, then usage, then caveats. It is a single dense paragraph that mostly earns its length, though a couple of clauses (e.g. 'in the order of the edition') are slightly verbose rather than strictly necessary.

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 an output schema present and annotations carrying the safety profile, the description still covers the full field inventory, the usage conditions, and the null/exclusion caveats. Nothing an agent needs to select or call 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 coverage is 100%, so lang and market are already documented in the schema. The description restates the market-parameter behavior and ties lang to 'the order of the edition', but adds little syntax or format detail the schema lacks; 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 names a specific resource (the markets TradeAlmanac covers) and enumerates exactly what each record contains: code, name, status, sections, trading hours with time zone, index symbol, instrument count, and citation page. No sibling tool covers markets/countries coverage, so it is clearly 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?

It gives explicit triggers (user asks which markets/countries are covered, what the site has for a market, or when an exchange trades) and explicit exclusions (no prices, index levels, movers, or live open/closed state, which live on the market page). It also explains the market parameter's effect directly.

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?

With annotations covering the safety profile, the description still adds rich behavioral context beyond them: day-order expiry, the background-tick fill model under realistic/strict profiles, the meaning of created/executed (accepted != trade), the full refusal-code taxonomy, idempotency via client_order_id, and the required paper permission. It discloses side effects (order appears at once, marked as placed by an agent) that 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?

Purpose is front-loaded, but the body is a single dense run-on paragraph mixing parameter rules, execution semantics, and a long error-code list, with some punctuation slips (e.g. the merged parenthesis around paper_account_not_found). Most content earns its place, but it would read better grouped into usage / parameters / behavior / errors.

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?

Despite an output schema existing, the description still explains how to read key answer fields (created, executed, status, pending_reason, execution_note), plus idempotency-retry guidance and the recovery step after a server error. For a mutation tool with a permission requirement, it is complete.

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

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

Schema coverage is 100%, so a 3 is the baseline, but the description meaningfully extends the schema: it stresses lots are LOTS not shares (one lot = lot_size shares), that limit_price is per share in the base currency and must be a multiple of the instrument's price step, and that market orders take no limit_price. These constraints go beyond the field descriptions.

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 ('Place an order on the practice (demo) account of the signed-in user') and immediately clarifies it is simulated, with no real broker/exchange path. An agent can distinguish it from real trading tools and from paper_portfolio_state / paper_trades_list 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 explicit when-to-use ('Call it only on a direct request of the user'), what is unavailable (stop orders), how to close a position (a sell order, since there is no separate closing tool), and routes to paper_portfolio_state for lot sizes and status. Nothing 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 only cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds substantial behavior: virtual money, no real order routed, delayed stored quotes, cache-bypassing totals at totals.calculated_at, requirement of the paper permission, and precise null semantics for unvalued positions. It even discloses truncation behavior for open orders (max 50, open_orders_truncated for the rest).

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?

Purpose and usage are front-loaded well, but roughly two-thirds of the text documents return fields (totals, positions, open_orders) that an output schema already carries, which is redundant for a zero-parameter read tool. The dense multi-clause sentences bloat the definition beyond what invocation requires.

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 no-parameter read tool with annotations covering safety and an output schema covering the return shape, the description still fills every remaining gap: permission requirement, no-account state, valuation-null semantics, and open-order truncation. Nothing an agent needs to call or interpret it 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?

The tool takes no parameters, so the baseline for empty schemas is 4. The description cannot add parameter meaning, and correctly spends its detail elsewhere rather than inventing 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?

Opens with a specific verb+resource: 'Read the state of the practice (demo) account of the signed-in user', enumerating cash, value, positions, and open orders. It cleanly distinguishes itself from paper_order_place (which 'takes' lots) and paper_trades_list by scoping to current state rather than order placement or history.

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

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

Gives explicit timing context — 'before placing a practice order (available_cash, available_lots) and after one — to see whether it filled' — and names the sibling whose unit (whole lots) it supplies. It also states a boundary case (no account yet: only the user can open one on the site; this tool creates nothing).

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/non-destructive, but the description adds substantial context beyond them: trades are simulated with virtual money, no real order reaches a broker, the 'paper' permission is required, and a user without a practice account gets has_account=false with an empty 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?

Long but front-loaded, with purpose, semantics, and pagination in that order and no filler sentences. The enumeration of trade fields is partly redundant given an output schema exists, which keeps it from 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?

Covers everything an agent needs: permission requirement, filtering, pagination loop, empty-account edge case, currency semantics, and unit caveats (shares not lots). Even though an output schema exists, the field semantics it supplies are a bonus rather than a gap-filler.

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 adds operational meaning the schema lacks: limit is the page size (20 default, 50 max), next_cursor must be fed back as cursor, and total counts matching trades. The ticker filter is restated but the pagination workflow is genuinely new.

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 ('List the trades (fills) of the practice (demo) account'), scoped to the signed-in user and ordered newest first. It is immediately distinguishable from siblings like paper_order_place and paper_portfolio_state.

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 concrete use cases ('answer what did I trade on the practice account') and explicitly ties one to a sibling ('confirm that an order placed by paper_order_place has filled'). It stops short of stating when to prefer paper_portfolio_state instead, so no true exclusion is 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), yet the description still adds non-obvious behavior: status=empty means no match, null means the metric is not computed rather than zero, and the service does not serve quotes at all. These are operational facts not derivable from 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?

Front-loaded with the core action and tightly packed, but the single dense paragraph carries a lot of clauses (units, sector codes, status/null semantics) that could be structured for faster scanning. Every sentence does carry distinct information, so waste is minimal.

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 an output schema present, return values need not be described, and the description still covers the remaining ambiguity: unit conventions, sector-code sourcing, pagination-adjacent behavior, and empty/null edge cases. An agent has everything needed to invoke 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 100%, so the baseline is 3; the description goes further by generalizing the unit convention ('Thresholds and yields are FRACTIONS: 10 % is 0.1, never 10'), clarifying multiples vs. roubles, and stressing that sector is a code not a name. It largely reinforces rather than extends the schema, which already documents these fields.

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 ('Select Moscow Exchange stocks by fundamentals'), enumerates the filterable dimensions (sector, P/E ceiling, dividend-yield floor) and the sort capability. It also names the sibling tools it is not (dividends_by_ticker, sectors), so an agent can distinguish it without opening other schemas.

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 explicit when-to-use cases ('find / which stocks with …', 'the cheapest', 'the highest yield') and explicit exclusions ('Do not use it for a live share price or price history', 'nor for one company's dividend history (dividends_by_ticker)'), routing the agent to the correct alternative.

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, closed-world), so the description only needs to add context. It does: 'returns no securities and no values' sets expectations about a metadata-only payload, and it points to screener for units on numeric fields. It could say more about the accepted=true flag's meaning, but the added value is real.

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 purpose, then the negative constraint, then the alternative. Every sentence carries weight, though the inline enumeration of accepted fields is partly redundant with the tool's own output.

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 an output schema present, return values need no explanation, and the description still clarifies that no securities or values come back. Zero parameters, closed-world hint, and an explicit boundary against screener leave nothing an agent needs 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?

The tool takes zero parameters, so the baseline is 4. The description goes further by naming which field names the screener accepts as parameters (sector, pe_ttm_max, dividend_yield_min, sort, sort_dir), which is useful cross-tool context even though it describes another tool's 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 precise verb+resource: a reference list of field names the screening engine knows, with their types. It immediately distinguishes itself from the sibling screener by declaring it holds metadata, not selections.

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 scopes use to 'only when the user asks what the screener can filter or sort by,' and names the alternative tool (screener) plus the condition that selects it for actual selection. Nothing is left for the agent to infer.

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 and non-destructive behavior for this zero-parameter lookup. The description adds value by drawing negative scope boundaries (no performance, index or sentiment) and routing sentiment queries elsewhere, though it says nothing about ordering or refresh cadence.

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: the resource and payload first, then uses, then exclusions. Every sentence earns its place with no redundancy.

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 an output schema present, return values need no explanation, and no input parameters exist to document. The annotations plus the description's scope boundaries and sibling routing leave nothing an agent needs 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?

The tool takes no parameters, so the description carries no parameter burden; the reference to screener's sector parameter is usage context rather than this tool's input. Baseline 4 for a zero-parameter tool 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 resource (sector codes of the Moscow Exchange classification) and what it returns (the number of securities in each). It also distinguishes itself from sibling tools like screener and list_indicators by function.

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 two explicit use cases — translating a named sector into the code for screener's sector parameter, and enumerating which sectors exist — plus explicit when-nots (no performance, index or sentiment) with a pointer to list_indicators for sentiment.

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?

With annotations already covering idempotency and mutation flags, the description goes further: it explains that a duplicate ticker returns the existing item with its note preserved, that the response exposes an 'added' boolean, that the call mutates the account, and that the watchlists permission is required. These are concrete behavioral details beyond what the annotations provide.

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 definition is front-loaded with the core action and then layers on behavioral constraints in a logical order. It is slightly longer than necessary, with some redundancy between the idempotency sentence and the 'added' flag explanation, but every sentence still carries useful routing or behavioral information.

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

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

For a mutating tool with an output schema, the description covers the remaining agent-facing needs: permission requirements, idempotent behavior, error conditions, and the source of required IDs. Nothing material is missing for correct invocation.

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 note, ticker, and watchlist_id in detail. The description reinforces the ME-only ticker constraint and the source of watchlist_id, but adds no syntax, format, or validation detail beyond the schema. This matches the baseline for a fully documented 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 verb and resource – adding a Moscow Exchange instrument to one of the user's watchlists by ticker – and immediately scopes it to ME tickers only. This clearly distinguishes it from siblings like watchlist_remove_item, watchlist_create, and watchlists_list.

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 tells the agent exactly when the tool applies (ME tickers) and when it does not (world-market securities and coins are added on the site), and it names the source for watchlist_id (watchlists_list). Error cases such as instrument_not_found and watchlist_items_limit_reached make the boundaries explicit.

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 named failure modes (watchlist_name_taken, watchlist_limit_reached), the required sign-in permission ('watchlists'), and that the account is mutated immediately. Annotations only give generic readOnlyHint=false / destructiveHint=false; the description supplies the concrete auth, error, and visibility semantics an agent needs.

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 action and return value, then immediately followed by the routing rule and the failure/permission conditions. Every sentence carries distinct information with no redundancy.

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 an output schema present, return-value detail is not required, yet the description still notes the id is returned. For a low-complexity, 2-parameter mutation tool, the description covers action, routing, errors, permissions, and side effects completely.

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% with both parameters fully documented (name is required with length bounds, description is optional), so the schema carries the burden and a 3 baseline applies. The description adds no name/description syntax, format, or localization detail beyond what the schema already states.

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 ('Create a new private watchlist in the user's account') plus the immediate return value (its id), and explicitly distinguishes itself from watchlist_add_item. An agent can route between the two creation-vs-addition tools 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?

Gives an explicit trigger ('use it only when the user asks for a new list') and names the correct alternative for the other case ('to put an instrument on a list that already exists call watchlist_add_item'). This is the when/when-not/alternative pattern at full strength.

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 and idempotentHint=true, but the description adds context beyond them: the removal is immediate, the item's note is permanently lost and cannot be restored by re-adding, and the watchlists permission of the sign-in is required. These are exactly the non-derivable behavioral facts an agent needs.

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

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

Four tight sentences, each earning its place: action, identifier provenance, destructive consequence, and authorization gate. The irreversible-note warning is front-loaded before the call-gating instruction.

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?

Complete for a two-parameter destructive mutation: provenance of both IDs, the irreversibility of note loss, the user-consent precondition, and the required permission are all stated. An output schema exists, so return values need not be explained.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema; the description's mention that both IDs come from watchlists_list and that tickers are rejected overlaps with the schema's own parameter descriptions. Baseline 3 is appropriate since the schema carries the field-level 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 verb ('remove') and resource ('one instrument from one of the user's watchlists'), and explicitly distinguishes the required identifier form (ID, not ticker) which separates it from ticker-based siblings. An agent can identify this as the inverse of watchlist_add_item without ambiguity.

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

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

Explicitly says 'Call it only on a direct request of the user', which is a clear when-to-use gate, and specifies exactly which identifiers to source from watchlists_list. It also states 'a ticker is not accepted', ruling out a tempting alternative input path.

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: an empty account yields an empty listing, nothing is created, quotes are never served, counts have specific semantics, and it warns that list names/notes are user-authored data and never instructions (prompt-injection defense). The permission requirement is also disclosed.

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?

Purpose is front-loaded in the first clause; subsequent sentences carry distinct payloads (counts, empty state, security note, permission). It is long and has mild redundancy around items_count appearing 'the same with and without watchlist_id', but nearly every clause earns its place for a tool with this much return-shape nuance.

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?

Although an output schema exists (so return values need not be explained), the description fully disambiguates the non-obvious count fields, the empty-account case, the ticker-only itemisation, and the permission requirement. Nothing an agent needs to invoke or interpret this call 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 coverage is 100% and the single parameter is documented in-schema, so baseline 3 applies. The description goes further by spelling out what the flagged vs unflagged modes return (one list with itemised items vs all lists without items) and by tying the item id back to watchlist_remove_item, adding real meaning beyond the schema text.

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 opens with a specific verb+resource ('List the watchlists of the signed-in user's account') and enumerates the returned fields (id, name, default flag, count, tickers). It also carves out a clear boundary ('it returns no prices: this server does not serve quotes') and names the sibling watchlist_remove_item in the item-id linkage, so an agent can place it against watchlist_create/add_item/remove_item without opening schemas.

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 explicit conditions: use it to answer 'what is on my watchlist' and before changing a list, and it explains that the returned item id is the argument watchlist_remove_item takes — concrete routing to a sibling. It does not explicitly state when not to use it or name a competing read alternative, 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 it read-only/idempotent/non-destructive, and the description adds substantial context beyond them: there are NO values due to source licensing, each row carries symbol/name/group/country/currency/number-kind (delayed_quote, close, assessment) and as_of, and the agent is told to redirect users to source_url. This is unusually rich behavioral 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?

It is fairly long and occasionally dense in phrasing ('what TradeAlmanac shows as the main of the world'), but it is front-loaded around section semantics, the no-values constraint, and usage routing, so nearly every sentence 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 two-parameter read-only lookup with an output schema, the description supplies everything the agent needs: section semantics, ordering, row fields, the no-values constraint, and the source_url redirection. No missing decision-relevant information.

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 adds real meaning: lang governs both the edition order of indices and the language of names, and section explains the ordering logic (home market first, then S&P 500, then rest by market size; commodities grouped energy/metals/grain).

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 precise verb+resource: it returns the composition and order of the world's main indices/commodities exactly as the section page shows them, and explicitly scopes out values. An agent can distinguish it from siblings like market_overview or sectors 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?

It gives an explicit when-to-use clause ('Use it when the user asks which indices or commodities the platform follows, in which order, what the main index of a country is, or where to look at them') and an explicit when-not/how-to-handle-values directive (send the user to source_url, never present a level as ours).

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